Implement math:pow and math:pow10

To facilitate using the `^` character for line continuation we need to
remove its use an an exponentiation function. So introduce `math:pow`
and `math:pow10` as alternatatives and mark `^` as deprecated.

Related #989

pkg/eval/builtin_fn_num.go

@@ -78,6 +78,9 @@ import (
 // ~> ^ 2 0.5
 // ▶ 1.4142135623730951
 // ```
+//
+// This function is deprecated; use [math:pow](math.html#mathpow) or
+// [math:pow10](math.html#mathpow10) instead.
 
 //elvdoc:fn < <= == != > >=
 //

pkg/eval/compiler.go

@@ -162,6 +162,8 @@ func (cp *compiler) checkDeprecatedBuiltin(name string, r diag.Ranger) {
 		msg = `the "replaces" command is deprecated; use "str:replace" instead`
 	case "-time~":
 		msg = `the "-time" command is deprecated; use "time" instead`
+	case "^~":
+		msg = `the "^" command is deprecated; use "math:pow" or "math:pow10" instead`
 	default:
 		return
 	}

pkg/eval/math/math.go

@@ -285,6 +285,42 @@ import (
 // ▶ (float64 NaN)
 // ```
 
+//elvdoc:fn pow
+//
+// ```elvish
+// math:pow $base $exponent
+// ```
+//
+// Output the result of raising `$base` to the power of `$exponent`. Examples:
+//
+// ```elvish-transcript
+// ~> math:pow 3 2
+// ▶ (float64 9)
+// ~> math:pow -2 2
+// ▶ (float64 4)
+// ```
+//
+// @cf math:pow10
+
+//elvdoc:fn pow10
+//
+// ```elvish
+// math:pow10 $exponent
+// ```
+//
+// Output the result of raising ten to the power of `$exponent` which must be
+// an integer. Note that `$exponent > 308` results in +Inf and `$exponent <
+// -323` results in zero. Examples:
+//
+// ```elvish-transcript
+// ~> math:pow10 2
+// ▶ (float64 100)
+// ~> math:pow10 -3
+// ▶ (float64 0.001)
+// ```
+//
+// @cf math:pow
+
 //elvdoc:fn round
 //
 // ```elvish
@@ -426,6 +462,8 @@ var fns = map[string]interface{}{
 	"log":           math.Log,
 	"log10":         math.Log10,
 	"log2":          math.Log2,
+	"pow":           math.Pow,
+	"pow10":         math.Pow10,
 	"round":         math.Round,
 	"round-to-even": math.RoundToEven,
 	"sin":           math.Sin,

pkg/eval/math/math_test.go

@@ -146,5 +146,15 @@ func TestMath(t *testing.T) {
 
 		That(`math:atanh 0`).Puts(math.Atanh(0)),
 		That(`math:atanh 1`).Puts(math.Inf(1)),
+
+		That(`math:pow nan 2`).Puts(math.NaN()),
+		That(`math:pow inf 2`).Puts(math.Inf(1)),
+		That(`math:pow 1 3`).Puts(1.0),
+		That(`math:pow 2 3`).Puts(8.0),
+		That(`math:pow -2 2`).Puts(4.0),
+
+		That(`math:pow10 0`).Puts(1.0),
+		That(`math:pow10 3`).Puts(1000.0),
+		That(`math:pow10 -3`).Puts(0.001),
 	)
 }