\name{eval_operator}
\alias{eval_operator}
\title{Evaluate an Operator or Composition}
\description{
Evaluates a single operator by substituting resolved arguments into its translation string, or composes two elements without an operator using compositional rules.

This function contains the complete translation logic: extraction of specific meanings from \code{\{specific\}} annotations, article insertion (\code{"the "}), verb-prefix stripping (\code{"to "}), placeholder substitution, and composition rules.
}
\usage{
eval_operator(operator, rule_translation, args = list(), seps = "", trailing_sep = "")
}
\arguments{
  \item{operator}{Type string of the operator (e.g. \code{"Sx->V"}, \code{"SSx->V"}, \code{"xS->A"}), or \code{NULL} for composition (no operator present). For base types without arguments (e.g. \code{"S"}, \code{"V"}), pass the type string here.}
  \item{rule_translation}{Translation string with placeholders (e.g. \code{"to utilize S"}, \code{"S1 and therefore S2"}), or \code{NULL} for composition.}
  \item{args}{List of \code{c(name, translation)} character vectors:
    \describe{
      \item{name}{Placeholder name encoding the grammatical type (e.g. \code{"S"}, \code{"S1"}, \code{"V"}, \code{"SEN2"}). The type is reconstructed internally by stripping the trailing index digits.}
      \item{translation}{Resolved translation of the argument.}
    }
    Default: \code{list()} (no arguments, for base types).
    The helper function \code{build_args()} can be used to construct this list from a set of elements.
  }
  \item{seps}{Character vector of separators between elements, as extracted by \code{\link{apply_translation_rules}}. Hyphens in separators are converted to spaces for composition. Default: \code{""}.}
  \item{trailing_sep}{Text after the last element (e.g. trailing punctuation). Hyphens are converted to spaces for composition. Default: \code{""}.}
}
\details{
The function operates in two modes:

\strong{Operator mode} (\code{operator} is not \code{NULL}):
\enumerate{
  \item Determine the result type from the operator string via \code{parse_type()}.
  \item For each argument, apply transformations:
    \itemize{
      \item Strip \code{"to "} from verb-type (\code{"V"}) arguments.
      \item Add \code{"the "} before substantive (\code{"S"}) arguments when the result type is not \code{"S"} (i.e., the operator changes the type).
    }
  \item Replace each placeholder in \code{rule_translation} by whole-word match.
}

\strong{Composition mode} (\code{operator} is \code{NULL}):

Exactly two arguments are required. The composition rules are:
\describe{
  \item{S + A \verb{->} S}{Simple juxtaposition: \code{"X Y"}.}
  \item{S + S \verb{->} S}{Without comma separator: \code{"X of/with the Y"}.}
  \item{S, S \verb{->} S}{With comma separator: \code{"X, the Y"}.}
  \item{S + V \verb{->} SEN}{Subject-verb: \code{"X Y"} (with \code{"to "} stripped from verb).}
  \item{SEN + SEN \verb{->} SEN}{Sentence concatenation: \code{"X. Y"} (period added if missing).}
}

In both modes, translations of the form \code{"general \{specific\}"} are reduced to the specific part before processing.
}
\value{
A character vector of length 2: \code{c(result_type, result_translation)}.

On error (e.g. incompatible types in composition), a character vector of length 1 containing the error message.
}
\examples{
# --- Base type (operator without arguments) ---
# A simple substantive passes through unchanged:
sumer:::eval_operator("S", "temple")
# [1] "S"      "temple"

# With {specific} extraction:
sumer:::eval_operator("S", "place {earth}")
# [1] "S"     "earth"

# --- Operator with one argument: Sx->V ---
# The S argument gets "the " prepended (since result type is V, not S):
args <- list(c("S", "temple"))
sumer:::eval_operator("Sx->V", "to utilize S", args)
# [1] "V"                      "to utilize the temple"

# --- Operator with two S arguments: SSx->V ---
# Duplicate types get indexed names (S1, S2):
args <- list(c("S1", "leader"), c("S2", "temple"))
sumer:::eval_operator("SSx->V", "to equip S1 with S2", args)
# [1] "V"                                  "to equip the leader with the temple"

# --- Composition: S + A -> S ---
args <- list(c("S", "temple"), c("A", ", which is a great one"))
sumer:::eval_operator(NULL, NULL, args)
# [1] "S"            "temple, which is a great one"

# --- Composition: S + V -> SEN ---
args <- list(c("S", "men"), c("V", "to bring grain into the temple"))
sumer:::eval_operator(NULL, NULL, args)
# [1] "SEN"       "men bring grain into the temple"

# --- Full pipeline with add_brackets and apply_translation_rules ---
x <- "mec3-ki-aj2-ga-ce-er"
x <- as.cuneiform(x)
x

meaning <- rbind( c("S",      "a man who relies on his own strength"),
                  c("S",      "place {earth}"),
                  c("Sx->A",  ", whose allocated resource is S"),
                  c("xS->A",   ", whose sustenance is S"),
                  c("S",      "grain"),
                  c("Sx->S",  "lamented S"))

df <- data.frame(
    type  = meaning[,1],
    translation = meaning[,2],
    expr  = split_sumerian(x)$signs)

s <- x
for(i in 1:nrow(df)){
 s <- sub(df$expr[i], paste0("#", i), s)
}
s

s_bracketed <- sumer:::add_brackets(s, df$type)
s_bracketed

apply_translation_rules(s_bracketed$string, df$type, df$translation)
}

\seealso{
\code{\link{apply_translation_rules}} which calls this function,
\code{\link{compose_skeleton_entry}} for the full pipeline
}
\keyword{internal}
