Operator overloading (#753)

This patch allows you to implement operator overloading in OSL -- for
example, if you define a type like

    struct vector4 {
        float x, y, z, w;
    };

you can also define math operators in the following manner:

    vector4 __operator__add__ (vector4 a, vector4 b) {
        return vector4 (a.x+b.x a.y+b.y, a.z+b.z, a.w+b.w);
    }

and then use plain old `+` as you would for any built-in types:

    vector4 a, b, c;
    c = a + b;    // automatically calls __operator__add__(vector4,vector4)

It's fairly straightforward: for any of the usual unary and binary
operators, if a function called __operator__NAME__ is visible from
the current scope and the types match, it is understood that the
operator really means a function call to that special function.
The valid NAME choices are add, sub, mul, div, neg, and so on. See
the docs for full list, but it's pretty obvious.

With great power comes great responsibility! Use this wisely -- that is,
sparingly, and only when the operator is exactly analogous to how it
works with the built-in types. Same general guidance about using it in
C++.

Author: lgritz

CMakeLists.txt

@@ -252,6 +252,7 @@ TESTSUITE ( and-or-not-synonyms aastep arithmetic array array-derivs array-range
             noise-gabor noise-gabor2d-filter noise-gabor3d-filter
             noise-perlin noise-uperlin noise-simplex noise-usimplex
             pnoise pnoise-cell pnoise-gabor pnoise-perlin pnoise-uperlin
+            operator-overloading
             oslc-comma oslc-D
             oslc-err-arrayindex oslc-err-closuremul
             oslc-err-format oslc-err-intoverflow

src/doc/languagespec.tex

@@ -61,8 +61,8 @@
 Editor: Larry Gritz \\
 \emph{lg@imageworks.com}
 }
-\date{{\large Date: 6 Feb 2017 \\
- (with corrections, 12 May 2017)
+\date{{\large Date: 16 May 2017 \\
+% (with corrections, 12 May 2017)
 }
 \bigskip
 \bigskip
@@ -886,7 +886,7 @@ \section{Preprocessor}
 \end{tabular}
 
 
-\chapter{Gross syntax, shader types, parameters, functions}
+\chapter{Gross syntax, shader types, parameters}
 \label{chap:grosssyntax}
 
 The overall structure of a shader is as follows:
@@ -1336,48 +1336,6 @@ \section{Shader metadata}
 
 
 \newpage
-\section{Functions}
-\label{sec:functions}
-\index{functions!declarations}
-
-You may define functions much like in C or C++.
-
-\begin{quote}
-\em
-return-type ~ function-name ~ {\rm\cf (} optional-parameters {\rm\cf )} \\
-\rm
-{\cf \{ } \\
-\em
-\spc statements
-
-{\cf \} }
-\end{quote}
-
-Parameters to functions are similar to shader parameters, except that
-they do not permit initializers.  A function call must pass values for
-all formal parameters.  Function parameters in \langname are all
-\emph{passed by reference}, and are read-only within the body of the
-function unless they are also designated as {\cf output} (in the same
-manner as output shader parameters).
-
-Like for shaders, statements inside functions may be actual executions
-(assignments, function call, etc.), local variable declarations (visible
-only from within the body of the function), or local function
-declarations (callable only from within the body of the function).
-
-The return type may be any simple data type, a {\cf struct}, or a {\cf
-  closure}.  Functions may not return arrays.  The return type may be
-{\cf void}, indicating that the function does not return a value (and
-should not contain a {\cf return} statement).  A {\cf return} statement
-inside the body of the function will halt execution of the function at
-that point, and designates the value that will be returned (if not a
-{\cf void} function).
-
-Functions may be \emph{overloaded}.  That is, multiple functions may be
-defined to have the same name, as long as they have differently-typed
-parameters, so that when the function is called the list of arguments
-can disambiguate which version of the function is desired.
-
 \section{Public methods}
 \label{sec:publicmethods}
 \indexapi{public}
@@ -2632,7 +2590,10 @@ \section{Control flow: {\cf if, while, do, for}}
 and proceeds to the next iteration of the loop.
 
 \section{Functions}
-\label{sec:syntax:functions}
+\label{sec:functions}
+
+\subsection{Function calls}
+\label{sec:syntax:functioncalls}
 \index{function calls}
 
 Function calls are very similar to C and related programming languages:
@@ -2651,8 +2612,111 @@ \section{Functions}
 semantics, except if you pass the same variable as two separate
 arguments to a function that modifies an argument's value.
 
-Function definitions are described in detail in Section~\ref{sec:functions}.
 
+\subsection{Function definitions}
+\label{sec:syntax:functiondefinitions}
+\index{functions!definitions}
+
+You may define functions much like in C or C++.
+
+\begin{quote}
+\em
+return-type ~ function-name ~ {\rm\cf (} optional-parameters {\rm\cf )} \\
+\rm
+{\cf \{ } \\
+\em
+\spc statements
+
+{\cf \} }
+\end{quote}
+
+Parameters to functions are similar to shader parameters, except that
+they do not permit initializers.  A function call must pass values for
+all formal parameters.  Function parameters in \langname are all
+\emph{passed by reference}, and are read-only within the body of the
+function unless they are also designated as {\cf output} (in the same
+manner as output shader parameters).
+
+Like for shaders, statements inside functions may be actual executions
+(assignments, function call, etc.), local variable declarations (visible
+only from within the body of the function), or local function
+declarations (callable only from within the body of the function).
+
+The return type may be any simple data type, a {\cf struct}, or a {\cf
+  closure}.  Functions may not return arrays.  The return type may be
+{\cf void}, indicating that the function does not return a value (and
+should not contain a {\cf return} statement).  A {\cf return} statement
+inside the body of the function will halt execution of the function at
+that point, and designates the value that will be returned (if not a
+{\cf void} function).
+
+Functions may be \emph{overloaded}.  That is, multiple functions may be
+defined to have the same name, as long as they have differently-typed
+parameters, so that when the function is called the list of arguments
+can disambiguate which version of the function is desired.
+
+\subsection{Operator overloading}
+\label{sec:syntax:operatoroverloading}
+\index{operator overloading}
+
+\NEW  % 1.9
+OSL permits \emph{operator overloading}, which is the practice of providing
+a function that will be called when you use an operator like {\cf +} or
+{\cf *}. This is especially handy when you use {\cf struct} to define
+mathematical types and wish for the usual math operators to work with them.
+Here is a typical example, which also shows the special naming convention
+that allows operator overloading:
+
+\begin{code}
+    struct vector4 {
+        float x, y, z, w;
+    };
+
+    vector4 __operator__add__ (vector4 a, vector4 b) {
+        return vector4 (a.x+b.x, a.y+b.y, a.z+b.z, a.w+b.w);
+    }
+
+    shader test ()
+    {
+        vector4 a = vector4 (.2, .3, .4, .5);
+        vector4 b = vector4 (1, 2, 3, 4);
+
+        vector4 c = a + b;   // Will call __operator__add__(vector4,vector4)
+        printf ("a+b = %g %g %g %g\n", c.x, c.y, c.z, c.w);
+    }
+\end{code}
+
+\noindent The full list of these special function names is as follows (in
+order of decreasing operator precedence):
+
+\smallskip
+
+\begin{tabular}{ p{0.5in} p{2in} p{1.75in}}
+%op & overload function name & ~ \\
+%\hline
+{\cf \bfseries -} & {\cf __operator__neg__} & unary negation \\
+{\cf \bfseries \textasciitilde} & {\cf __operator__compl__} & unary bitwise complement \\
+{\cf \bfseries !} & {\cf __operator__not__} & unary boolean `not' \\[1.5ex]
+{\cf \bfseries *} & {\cf __operator__mul__} &  \\
+{\cf \bfseries /} & {\cf __operator__div__} &  \\
+{\cf \bfseries \%} & {\cf __operator__mod__} &  \\
+{\cf \bfseries +} & {\cf __operator__add__} &  \\
+{\cf \bfseries -} & {\cf __operator__sub__} &  \\[1.5ex]
+{\cf \bfseries <<} & {\cf __operator__shl__} & \\
+{\cf \bfseries >>} & {\cf __operator__shr__} & \\[1.5ex]
+{\cf \bfseries <} & {\cf __operator__lt__} &  \\
+{\cf \bfseries <=} & {\cf __operator__le__} &  \\
+{\cf \bfseries >} & {\cf __operator__gt__} &  \\
+{\cf \bfseries >=} & {\cf __operator__ge__} & \\
+{\cf \bfseries ==} & {\cf __operator__eq__} & \\
+{\cf \bfseries !=} & {\cf __operator__ne__} & \\[1.5ex]
+{\cf \bfseries \&} & {\cf __operator__bitand__} & \\
+{\cf \bfseries \textasciicircum} & {\cf __operator__xor__} & \\
+{\cf \bfseries |} & {\cf __operator__bitor__} & \\
+%{\cf \bfseries \&\&} & {\cf __operator__and__} & boolean and \\
+%{\cf \bfseries ||} & {\cf __operator__or__} & boolean or \\
+%\hline
+\end{tabular}
 
 
 \section{Global variables}

src/liboslcomp/ast.cpp

@@ -854,6 +854,18 @@ ASTassign_expression::opword () const
 
 
 
+ASTunary_expression::ASTunary_expression (OSLCompilerImpl *comp, int op,
+                                          ASTNode *expr)
+    : ASTNode (unary_expression_node, comp, op, expr)
+{
+    // Check for a user-overloaded function for this operator
+    Symbol *sym = comp->symtab().find (ustring::format ("__operator__%s__", opword()));
+    if (sym && sym->symtype() == SymTypeFunction)
+        m_function_overload = (FunctionSymbol *)sym;
+}
+
+
+
 const char *
 ASTunary_expression::childname (size_t i) const
 {
@@ -891,6 +903,22 @@ ASTunary_expression::opword () const
 
 
 
+ASTbinary_expression::ASTbinary_expression (OSLCompilerImpl *comp, Operator op,
+                                            ASTNode *left, ASTNode *right)
+    : ASTNode (binary_expression_node, comp, op, left, right)
+{
+    // Check for a user-overloaded function for this operator.
+    // Disallow a few ops from overloading.
+    if (op != And && op != Or) {
+        ustring funcname = ustring::format ("__operator__%s__", opword());
+        Symbol *sym = comp->symtab().find (funcname);
+        if (sym && sym->symtype() == SymTypeFunction)
+            m_function_overload = (FunctionSymbol *)sym;
+    }
+}
+
+
+
 const char *
 ASTbinary_expression::childname (size_t i) const
 {
@@ -985,13 +1013,14 @@ ASTtype_constructor::childname (size_t i) const
 
 
 ASTfunction_call::ASTfunction_call (OSLCompilerImpl *comp, ustring name,
-                                    ASTNode *args)
+                                    ASTNode *args, FunctionSymbol *funcsym)
     : ASTNode (function_call_node, comp, 0, args), m_name(name),
       m_argread(~1),      // Default - all args are read except the first
       m_argwrite(1),      // Default - first arg only is written by the op
       m_argtakesderivs(0) // Default - doesn't take derivs
 {
-    m_sym = comp->symtab().find (name);
+    // If we weren't passed a function symbol directly, look it up.
+    m_sym = funcsym ? funcsym : comp->symtab().find (name);
     if (! m_sym) {
         error ("function '%s' was not declared in this scope", name.c_str());
         // FIXME -- would be fun to troll through the symtab and try to

src/liboslcomp/ast.h

@@ -159,6 +159,9 @@ class ASTNode : public OIIO::RefCnt {
     /// reference-counted pointer to *this.
     ref append (ref &x) { append (x.get()); return this; }
 
+    /// Detatch any 'next' nodes.
+    void detach_next () { m_next.reset(); }
+
     /// Concatenate ASTNode sequences A and B, returning a raw pointer to
     /// the concatenated sequence.  This is robust to either A or B or
     /// both being NULL.
@@ -290,6 +293,11 @@ class ASTNode : public OIIO::RefCnt {
     ///
     void typecheck_children (TypeSpec expected = TypeSpec());
 
+    /// Helper for check_arglist: simple case of checking a single arg type
+    /// agaisnt the front of the formals list (which will be advanced).
+    bool check_simple_arg (const TypeSpec &argtype,
+                           const char * &formals, bool coerce);
+
     /// Type check a list (whose head is given by 'arg' against the list
     /// of expected types given in encoded form by 'formals'.
     bool check_arglist (const char *funcname, ref arg,
@@ -731,9 +739,7 @@ class ASTassign_expression : public ASTNode
 class ASTunary_expression : public ASTNode
 {
 public:
-    ASTunary_expression (OSLCompilerImpl *comp, int op, ASTNode *expr)
-        : ASTNode (unary_expression_node, comp, op, expr)
-    { }
+    ASTunary_expression (OSLCompilerImpl *comp, int op, ASTNode *expr);
 
     const char *nodetypename () const { return "unary_expression"; }
     const char *childname (size_t i) const;
@@ -743,6 +749,8 @@ class ASTunary_expression : public ASTNode
     Symbol *codegen (Symbol *dest = NULL);
 
     ref expr () const { return child (0); }
+private:
+    FunctionSymbol *m_function_overload = nullptr;
 };
 
 
@@ -751,9 +759,7 @@ class ASTbinary_expression : public ASTNode
 {
 public:
     ASTbinary_expression (OSLCompilerImpl *comp, Operator op,
-                          ASTNode *left, ASTNode *right)
-        : ASTNode (binary_expression_node, comp, op, left, right)
-    { }
+                          ASTNode *left, ASTNode *right);
 
     const char *nodetypename () const { return "binary_expression"; }
     const char *childname (size_t i) const;
@@ -765,6 +771,8 @@ class ASTbinary_expression : public ASTNode
     ref left () const { return child (0); }
     ref right () const { return child (1); }
 private:
+    FunctionSymbol *m_function_overload = nullptr;
+
     // Special code generation for short-circuiting logical ops
     Symbol *codegen_logic (Symbol *dest);
 };
@@ -853,7 +861,8 @@ class ASTtype_constructor : public ASTNode
 class ASTfunction_call : public ASTNode
 {
 public:
-    ASTfunction_call (OSLCompilerImpl *comp, ustring name, ASTNode *args);
+    ASTfunction_call (OSLCompilerImpl *comp, ustring name, ASTNode *args,
+                      FunctionSymbol *funcsym = nullptr);
     const char *nodetypename () const { return "function_call"; }
     const char *childname (size_t i) const;
     const char *opname () const;

src/liboslcomp/codegen.cpp

@@ -1360,6 +1360,15 @@ ASTunary_expression::codegen (Symbol *dest)
 {
     // Code generation for unary expressions (-x, !x, etc.)
 
+    if (m_function_overload) {
+        // A little crazy, but we temporarily construct an ASTfunction_call
+        // in order to codegen this overloaded operator.
+        ustring funcname = ustring::format ("__operator__%s__", opword());
+        ASTfunction_call fc (m_compiler, funcname, expr().get(), m_function_overload);
+        fc.typecheck (typespec());
+        return dest = fc.codegen (dest);
+    }
+
     if (m_op == Not) {
         // Special case for logical ops
         return expr()->codegen_int (NULL, true /*boolify*/, true /*invert*/);
@@ -1396,6 +1405,27 @@ ASTunary_expression::codegen (Symbol *dest)
 Symbol *
 ASTbinary_expression::codegen (Symbol *dest)
 {
+    if (m_function_overload) {
+        // A little crazy, but we temporarily construct an ASTfunction_call
+        // in order to codegen this overloaded operator. Slightly tricky
+        // is that we need to concatenate our left and right arguments into
+        // an arg list.
+        ustring funcname = ustring::format ("__operator__%s__", opword());
+        if (left()->nextptr() || right()->nextptr()) {
+            error ("Overloaded %s cannot be passed arguments %s and %s",
+                   funcname, left()->nodetypename(), right()->nodetypename());
+            return dest;
+        }
+        ref args = left();
+        args->append (right().get());
+        ASTfunction_call fc (m_compiler, funcname, args.get(), m_function_overload);
+        fc.typecheck (typespec());
+        dest = fc.codegen (dest);
+        // now put things back the way we found them
+        left()->detach_next ();
+        return dest;
+    }
+
     // Special case for logic ops that short-circuit
     if (m_op == And || m_op == Or)
         return codegen_logic (dest);