refines the Theory.Target.matches and adds the matching function (#1429)

The matching function now takes the nicknames of the ancestors into
account. And a new `Theory.Target.matching` function returns the
actual target that matched with the name.

Author: ivg

lib/bap_core_theory/bap_core_theory.mli

@@ -1458,7 +1458,7 @@ module Theory : sig
 
     (** [read ?package name] is a synonym for [get ?package name].
 
-        Introduces for the consistency with the [Enum.S] interface.
+        Introduced for the consistency with the [Enum.S] interface.
     *)
     val read : ?package:string -> string -> t
 
@@ -1480,10 +1480,30 @@ module Theory : sig
     (** [name target] is the unique name of the target.  *)
     val name : t -> KB.Name.t
 
-    (** [matches target name] is true if [name] matches either
-        the unqualified name of the target itsef or one of its
-        ancestors; or if the name matches one of the target
-        nicknames. E.g., [matches target "mips"].
+
+    (** [matching t name] the target that matches [name].
+
+        [matching t name] is [Some r] where [r] is [t] or the closest
+        ancestor of [t] such that [r]'s name is equal to [name] or one
+        of name is [r]'s nicknames.
+
+        @since 2.5.0
+    *)
+    val matching : t -> string -> t option
+
+
+    (** [matches t name] when {!matching t name} is not [None].
+
+        [matching t name] is true when [name] matches either the
+        unqualified name of the target itsef or one of its ancestors;
+        or if the name matches one of the target nicknames or the
+        target parents nicknames.
+
+        E.g., [matches target "mips"].
+
+        @before 2.5.0 the nicknames of the ancestors weren't taken
+        into account
+        @after 2.5.0 uses the ancestors nicknames for matching
     *)
     val matches : t -> string -> bool
 
@@ -1515,7 +1535,7 @@ module Theory : sig
     *)
     val parents : t -> t list
 
-    (** [family p] returns an ordered list of targets that {!belongs} [p].
+    (** [family p] an ordered list of targets s.t. each {!belongs} to [p].
 
         The family members are ordered according to their hierarchy
         with [p] comming first.
@@ -2342,6 +2362,12 @@ module Theory : sig
       ?options:string list ->
       string -> compiler
 
+
+    (** [name compiler] returns the compiler name.
+
+        @since 2.5.0  *)
+    val name : compiler -> string
+
     (** [version] the compiler version.
 
         The least specific (aka major) version comes first in the

lib/bap_core_theory/bap_core_theory_program.mli

@@ -69,6 +69,7 @@ module Compiler : sig
     ?version:string list ->
     ?options:string list ->
     string -> compiler
+  val name : compiler -> string
   val version : compiler -> string list
   val options : compiler -> string list
   val specs : compiler -> string Map.M(String).t

lib/bap_core_theory/bap_core_theory_target.ml

@@ -547,14 +547,6 @@ let is_known c = not@@is_unknown c
 let rec belongs p c =
   Self.equal p c || is_known c && belongs p (parent c)
 
-let rec matches_name t name =
-  String.Caseless.equal (Name.unqualified (Self.name t)) name ||
-  is_known t && matches_name (parent t) name
-
-let rec matches t name =
-  let nicks = (info t).names in
-  Set.mem nicks name || matches_name t name
-
 let order t1 t2 : KB.Order.partial =
   if Self.equal t1 t2 then EQ
   else if belongs t1 t2 then LT
@@ -597,6 +589,20 @@ let partition xs =
 
 let families () = partition@@declared ()
 
+let matches_name t name =
+  String.Caseless.equal (Name.unqualified (Self.name t)) name
+
+let rec matching t name =
+  if matches_name t name || Set.mem (info t).names name
+  then Some t
+  else if is_known t then matching (parent t) name
+  else None
+
+
+let matches t name =
+  Option.is_some (matching t name)
+
+let nicknames t = (info t).names
 
 type alias = Alias.t
 

lib/bap_core_theory/bap_core_theory_target.mli

@@ -46,6 +46,7 @@ val unknown : t
 val is_unknown : t -> bool
 val name : t -> KB.Name.t
 val matches : t -> string -> bool
+val matching : t -> string -> t option
 val order : t -> t -> KB.Order.partial
 val belongs : t -> t -> bool
 val parent : t -> t