diff --git a/internal/chunkedfile/chunkedfile.go b/internal/chunkedfile/chunkedfile.go index 0751e85a..c50aa7d5 100644 --- a/internal/chunkedfile/chunkedfile.go +++ b/internal/chunkedfile/chunkedfile.go @@ -13,10 +13,10 @@ // // Example: // -// x = 1 / 0 ### "division by zero" -// --- -// x = 1 -// print(x + "") ### "int + string not supported" +// x = 1 / 0 ### "division by zero" +// --- +// x = 1 +// print(x + "") ### "int + string not supported" // // A client test feeds each chunk of text into the program under test, // then calls chunk.GotError for each error that actually occurred. Any diff --git a/lib/math/math.go b/lib/math/math.go index 07eb4a71..6676d073 100644 --- a/lib/math/math.go +++ b/lib/math/math.go @@ -17,53 +17,52 @@ import ( // Module math is a Starlark module of math-related functions and constants. // The module defines the following functions: // -// ceil(x) - Returns the ceiling of x, the smallest integer greater than or equal to x. -// copysign(x, y) - Returns a value with the magnitude of x and the sign of y. -// fabs(x) - Returns the absolute value of x as float. -// floor(x) - Returns the floor of x, the largest integer less than or equal to x. -// mod(x, y) - Returns the floating-point remainder of x/y. The magnitude of the result is less than y and its sign agrees with that of x. -// pow(x, y) - Returns x**y, the base-x exponential of y. -// remainder(x, y) - Returns the IEEE 754 floating-point remainder of x/y. -// round(x) - Returns the nearest integer, rounding half away from zero. +// ceil(x) - Returns the ceiling of x, the smallest integer greater than or equal to x. +// copysign(x, y) - Returns a value with the magnitude of x and the sign of y. +// fabs(x) - Returns the absolute value of x as float. +// floor(x) - Returns the floor of x, the largest integer less than or equal to x. +// mod(x, y) - Returns the floating-point remainder of x/y. The magnitude of the result is less than y and its sign agrees with that of x. +// pow(x, y) - Returns x**y, the base-x exponential of y. +// remainder(x, y) - Returns the IEEE 754 floating-point remainder of x/y. +// round(x) - Returns the nearest integer, rounding half away from zero. // -// exp(x) - Returns e raised to the power x, where e = 2.718281… is the base of natural logarithms. -// sqrt(x) - Returns the square root of x. +// exp(x) - Returns e raised to the power x, where e = 2.718281… is the base of natural logarithms. +// sqrt(x) - Returns the square root of x. // -// acos(x) - Returns the arc cosine of x, in radians. -// asin(x) - Returns the arc sine of x, in radians. -// atan(x) - Returns the arc tangent of x, in radians. -// atan2(y, x) - Returns atan(y / x), in radians. -// The result is between -pi and pi. -// The vector in the plane from the origin to point (x, y) makes this angle with the positive X axis. -// The point of atan2() is that the signs of both inputs are known to it, so it can compute the correct -// quadrant for the angle. -// For example, atan(1) and atan2(1, 1) are both pi/4, but atan2(-1, -1) is -3*pi/4. -// cos(x) - Returns the cosine of x, in radians. -// hypot(x, y) - Returns the Euclidean norm, sqrt(x*x + y*y). This is the length of the vector from the origin to point (x, y). -// sin(x) - Returns the sine of x, in radians. -// tan(x) - Returns the tangent of x, in radians. +// acos(x) - Returns the arc cosine of x, in radians. +// asin(x) - Returns the arc sine of x, in radians. +// atan(x) - Returns the arc tangent of x, in radians. +// atan2(y, x) - Returns atan(y / x), in radians. +// The result is between -pi and pi. +// The vector in the plane from the origin to point (x, y) makes this angle with the positive X axis. +// The point of atan2() is that the signs of both inputs are known to it, so it can compute the correct +// quadrant for the angle. +// For example, atan(1) and atan2(1, 1) are both pi/4, but atan2(-1, -1) is -3*pi/4. +// cos(x) - Returns the cosine of x, in radians. +// hypot(x, y) - Returns the Euclidean norm, sqrt(x*x + y*y). This is the length of the vector from the origin to point (x, y). +// sin(x) - Returns the sine of x, in radians. +// tan(x) - Returns the tangent of x, in radians. // -// degrees(x) - Converts angle x from radians to degrees. -// radians(x) - Converts angle x from degrees to radians. +// degrees(x) - Converts angle x from radians to degrees. +// radians(x) - Converts angle x from degrees to radians. // -// acosh(x) - Returns the inverse hyperbolic cosine of x. -// asinh(x) - Returns the inverse hyperbolic sine of x. -// atanh(x) - Returns the inverse hyperbolic tangent of x. -// cosh(x) - Returns the hyperbolic cosine of x. -// sinh(x) - Returns the hyperbolic sine of x. -// tanh(x) - Returns the hyperbolic tangent of x. +// acosh(x) - Returns the inverse hyperbolic cosine of x. +// asinh(x) - Returns the inverse hyperbolic sine of x. +// atanh(x) - Returns the inverse hyperbolic tangent of x. +// cosh(x) - Returns the hyperbolic cosine of x. +// sinh(x) - Returns the hyperbolic sine of x. +// tanh(x) - Returns the hyperbolic tangent of x. // -// log(x, base) - Returns the logarithm of x in the given base, or natural logarithm by default. +// log(x, base) - Returns the logarithm of x in the given base, or natural logarithm by default. // -// gamma(x) - Returns the Gamma function of x. +// gamma(x) - Returns the Gamma function of x. // // All functions accept both int and float values as arguments. // // The module also defines approximations of the following constants: // -// e - The base of natural logarithms, approximately 2.71828. -// pi - The ratio of a circle's circumference to its diameter, approximately 3.14159. -// +// e - The base of natural logarithms, approximately 2.71828. +// pi - The ratio of a circle's circumference to its diameter, approximately 3.14159. var Module = &starlarkstruct.Module{ Name: "math", Members: starlark.StringDict{ @@ -146,7 +145,8 @@ func newBinaryBuiltin(name string, fn func(float64, float64) float64) *starlark. }) } -// log wraps the Log function +// log wraps the Log function +// // as a Starlark built-in that accepts int or float arguments. func log(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) { var ( diff --git a/lib/proto/proto.go b/lib/proto/proto.go index 36f00233..e8b235d2 100644 --- a/lib/proto/proto.go +++ b/lib/proto/proto.go @@ -9,21 +9,21 @@ // // This package defines several types of Starlark value: // -// Message -- a protocol message -// RepeatedField -- a repeated field of a message, like a list +// Message -- a protocol message +// RepeatedField -- a repeated field of a message, like a list // -// FileDescriptor -- information about a .proto file -// FieldDescriptor -- information about a message field (or extension field) -// MessageDescriptor -- information about the type of a message -// EnumDescriptor -- information about an enumerated type -// EnumValueDescriptor -- a value of an enumerated type +// FileDescriptor -- information about a .proto file +// FieldDescriptor -- information about a message field (or extension field) +// MessageDescriptor -- information about the type of a message +// EnumDescriptor -- information about an enumerated type +// EnumValueDescriptor -- a value of an enumerated type // // A Message value is a wrapper around a protocol message instance. // Starlark programs may access and update Messages using dot notation: // -// x = msg.field -// msg.field = x + 1 -// msg.field += 1 +// x = msg.field +// msg.field = x + 1 +// msg.field += 1 // // Assignments to message fields perform dynamic checks on the type and // range of the value to ensure that the message is at all times valid. @@ -35,31 +35,30 @@ // performs a dynamic check to ensure that the RepeatedField holds // only elements of the correct type. // -// type(msg.uint32s) # "proto.repeated" -// msg.uint32s[0] = 1 -// msg.uint32s[0] = -1 # error: invalid uint32: -1 +// type(msg.uint32s) # "proto.repeated" +// msg.uint32s[0] = 1 +// msg.uint32s[0] = -1 # error: invalid uint32: -1 // // Any iterable may be assigned to a repeated field of a message. If // the iterable is itself a value of type RepeatedField, the message // field holds a reference to it. // -// msg2.uint32s = msg.uint32s # both messages share one RepeatedField -// msg.uint32s[0] = 123 -// print(msg2.uint32s[0]) # "123" +// msg2.uint32s = msg.uint32s # both messages share one RepeatedField +// msg.uint32s[0] = 123 +// print(msg2.uint32s[0]) # "123" // // The RepeatedFields' element types must match. // It is not enough for the values to be merely valid: // -// msg.uint32s = [1, 2, 3] # makes a copy -// msg.uint64s = msg.uint32s # error: repeated field has wrong type -// msg.uint64s = list(msg.uint32s) # ok; makes a copy +// msg.uint32s = [1, 2, 3] # makes a copy +// msg.uint64s = msg.uint32s # error: repeated field has wrong type +// msg.uint64s = list(msg.uint32s) # ok; makes a copy // // For all other iterables, a new RepeatedField is constructed from the // elements of the iterable. // -// msg.uints32s = [1, 2, 3] -// print(type(msg.uints32s)) # "proto.repeated" -// +// msg.uints32s = [1, 2, 3] +// print(type(msg.uints32s)) # "proto.repeated" // // To construct a Message from encoded binary or text data, call // Unmarshal or UnmarshalText. These two functions are exposed to @@ -75,7 +74,6 @@ // // See proto_test.go for an example of how to use the 'proto' // module in an application that embeds Starlark. -// package proto // TODO(adonovan): Go and Starlark API improvements: @@ -111,8 +109,8 @@ import ( // for a Starlark thread to use this package. // // For example: -// SetPool(thread, protoregistry.GlobalFiles) // +// SetPool(thread, protoregistry.GlobalFiles) func SetPool(thread *starlark.Thread, pool DescriptorPool) { thread.SetLocal(contextKey, pool) } @@ -305,10 +303,9 @@ func getFieldStarlark(thread *starlark.Thread, fn *starlark.Builtin, args starla // When a message descriptor is called, it returns a new instance of the // protocol message it describes. // -// Message(msg) -- return a shallow copy of an existing message -// Message(k=v, ...) -- return a new message with the specified fields -// Message(dict(...)) -- return a new message with the specified fields -// +// Message(msg) -- return a shallow copy of an existing message +// Message(k=v, ...) -- return a new message with the specified fields +// Message(dict(...)) -- return a new message with the specified fields func (d MessageDescriptor) CallInternal(thread *starlark.Thread, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) { dest := &Message{ msg: newMessage(d.Desc), @@ -1219,11 +1216,10 @@ func enumValueOf(enum protoreflect.EnumDescriptor, x starlark.Value) (protorefle // // An EnumValueDescriptor has the following fields: // -// index -- int, index of this value within the enum sequence -// name -- string, name of this enum value -// number -- int, numeric value of this enum value -// type -- EnumDescriptor, the enum type to which this value belongs -// +// index -- int, index of this value within the enum sequence +// name -- string, name of this enum value +// number -- int, numeric value of this enum value +// type -- EnumDescriptor, the enum type to which this value belongs type EnumValueDescriptor struct { Desc protoreflect.EnumValueDescriptor } diff --git a/lib/time/time.go b/lib/time/time.go index 0f781420..17999232 100644 --- a/lib/time/time.go +++ b/lib/time/time.go @@ -18,37 +18,37 @@ import ( // Module time is a Starlark module of time-related functions and constants. // The module defines the following functions: // -// from_timestamp(sec, nsec) - Converts the given Unix time corresponding to the number of seconds -// and (optionally) nanoseconds since January 1, 1970 UTC into an object -// of type Time. For more details, refer to https://pkg.go.dev/time#Unix. +// from_timestamp(sec, nsec) - Converts the given Unix time corresponding to the number of seconds +// and (optionally) nanoseconds since January 1, 1970 UTC into an object +// of type Time. For more details, refer to https://pkg.go.dev/time#Unix. // -// is_valid_timezone(loc) - Reports whether loc is a valid time zone name. +// is_valid_timezone(loc) - Reports whether loc is a valid time zone name. // -// now() - Returns the current local time. Applications may replace this function by a deterministic one. +// now() - Returns the current local time. Applications may replace this function by a deterministic one. // -// parse_duration(d) - Parses the given duration string. For more details, refer to -// https://pkg.go.dev/time#ParseDuration. +// parse_duration(d) - Parses the given duration string. For more details, refer to +// https://pkg.go.dev/time#ParseDuration. // -// parse_time(x, format, location) - Parses the given time string using a specific time format and location. -// The expected arguments are a time string (mandatory), a time format -// (optional, set to RFC3339 by default, e.g. "2021-03-22T23:20:50.52Z") -// and a name of location (optional, set to UTC by default). For more details, -// refer to https://pkg.go.dev/time#Parse and https://pkg.go.dev/time#ParseInLocation. +// parse_time(x, format, location) - Parses the given time string using a specific time format and location. +// The expected arguments are a time string (mandatory), a time format +// (optional, set to RFC3339 by default, e.g. "2021-03-22T23:20:50.52Z") +// and a name of location (optional, set to UTC by default). For more details, +// refer to https://pkg.go.dev/time#Parse and https://pkg.go.dev/time#ParseInLocation. // -// time(year, month, day, hour, minute, second, nanosecond, location) - Returns the Time corresponding to -// yyyy-mm-dd hh:mm:ss + nsec nanoseconds -// in the appropriate zone for that time -// in the given location. All the parameters -// are optional. -// The module also defines the following constants: +// time(year, month, day, hour, minute, second, nanosecond, location) - Returns the Time corresponding to +// yyyy-mm-dd hh:mm:ss + nsec nanoseconds +// in the appropriate zone for that time +// in the given location. All the parameters +// are optional. // -// nanosecond - A duration representing one nanosecond. -// microsecond - A duration representing one microsecond. -// millisecond - A duration representing one millisecond. -// second - A duration representing one second. -// minute - A duration representing one minute. -// hour - A duration representing one hour. +// The module also defines the following constants: // +// nanosecond - A duration representing one nanosecond. +// microsecond - A duration representing one microsecond. +// millisecond - A duration representing one millisecond. +// second - A duration representing one second. +// minute - A duration representing one minute. +// hour - A duration representing one hour. var Module = &starlarkstruct.Module{ Name: "time", Members: starlark.StringDict{ @@ -222,14 +222,15 @@ func (d Duration) Cmp(v starlark.Value, depth int) (int, error) { // Binary implements binary operators, which satisfies the starlark.HasBinary // interface. operators: -// duration + duration = duration -// duration + time = time -// duration - duration = duration -// duration / duration = float -// duration / int = duration -// duration / float = duration -// duration // duration = int -// duration * int = duration +// +// duration + duration = duration +// duration + time = time +// duration - duration = duration +// duration / duration = float +// duration / int = duration +// duration / float = duration +// duration // duration = int +// duration * int = duration func (d Duration) Binary(op syntax.Token, y starlark.Value, side starlark.Side) (starlark.Value, error) { x := time.Duration(d) @@ -329,6 +330,7 @@ func newTime(thread *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, } // String returns the time formatted using the format string +// // "2006-01-02 15:04:05.999999999 -0700 MST". func (t Time) String() string { return time.Time(t).String() } @@ -406,9 +408,10 @@ func (t Time) Cmp(yV starlark.Value, depth int) (int, error) { // Binary implements binary operators, which satisfies the starlark.HasBinary // interface -// time + duration = time -// time - duration = time -// time - time = duration +// +// time + duration = time +// time - duration = time +// time - time = duration func (t Time) Binary(op syntax.Token, y starlark.Value, side starlark.Side) (starlark.Value, error) { x := time.Time(t) diff --git a/starlark/profile.go b/starlark/profile.go index 590a4e2b..8967c3f4 100644 --- a/starlark/profile.go +++ b/starlark/profile.go @@ -363,19 +363,19 @@ func profile(w io.Writer) { // monotonic system clock, which there is no portable way to access. // Should that function ever go away, these alternatives exist: // -// // POSIX only. REALTIME not MONOTONIC. 17ns. -// var tv syscall.Timeval -// syscall.Gettimeofday(&tv) // can't fail -// return tv.Nano() +// // POSIX only. REALTIME not MONOTONIC. 17ns. +// var tv syscall.Timeval +// syscall.Gettimeofday(&tv) // can't fail +// return tv.Nano() // -// // Portable. REALTIME not MONOTONIC. 46ns. -// return time.Now().Nanoseconds() +// // Portable. REALTIME not MONOTONIC. 46ns. +// return time.Now().Nanoseconds() // -// // POSIX only. Adds a dependency. -// import "golang.org/x/sys/unix" -// var ts unix.Timespec -// unix.ClockGettime(CLOCK_MONOTONIC, &ts) // can't fail -// return unix.TimespecToNsec(ts) +// // POSIX only. Adds a dependency. +// import "golang.org/x/sys/unix" +// var ts unix.Timespec +// unix.ClockGettime(CLOCK_MONOTONIC, &ts) // can't fail +// return unix.TimespecToNsec(ts) // //go:linkname nanotime runtime.nanotime func nanotime() int64 diff --git a/starlark/unpack.go b/starlark/unpack.go index 31685899..df700a6e 100644 --- a/starlark/unpack.go +++ b/starlark/unpack.go @@ -44,23 +44,23 @@ type Unpacker interface { // // Examples: // -// var ( -// a Value -// b = MakeInt(42) -// c Value = starlark.None -// ) +// var ( +// a Value +// b = MakeInt(42) +// c Value = starlark.None +// ) // -// // 1. mixed parameters, like def f(a, b=42, c=None). -// err := UnpackArgs("f", args, kwargs, "a", &a, "b?", &b, "c?", &c) +// // 1. mixed parameters, like def f(a, b=42, c=None). +// err := UnpackArgs("f", args, kwargs, "a", &a, "b?", &b, "c?", &c) // -// // 2. keyword parameters only, like def f(*, a, b, c=None). -// if len(args) > 0 { -// return fmt.Errorf("f: unexpected positional arguments") -// } -// err := UnpackArgs("f", args, kwargs, "a", &a, "b?", &b, "c?", &c) +// // 2. keyword parameters only, like def f(*, a, b, c=None). +// if len(args) > 0 { +// return fmt.Errorf("f: unexpected positional arguments") +// } +// err := UnpackArgs("f", args, kwargs, "a", &a, "b?", &b, "c?", &c) // -// // 3. positional parameters only, like def f(a, b=42, c=None, /) in Python 3.8. -// err := UnpackPositionalArgs("f", args, kwargs, 1, &a, &b, &c) +// // 3. positional parameters only, like def f(a, b=42, c=None, /) in Python 3.8. +// err := UnpackPositionalArgs("f", args, kwargs, 1, &a, &b, &c) // // More complex forms such as def f(a, b=42, *args, c, d=123, **kwargs) // require additional logic, but their need in built-ins is exceedingly rare. @@ -79,17 +79,16 @@ type Unpacker interface { // for the zero values of variables of type *List, *Dict, Callable, or // Iterable. For example: // -// // def myfunc(d=None, e=[], f={}) -// var ( -// d Value -// e *List -// f *Dict -// ) -// err := UnpackArgs("myfunc", args, kwargs, "d?", &d, "e?", &e, "f?", &f) -// if d == nil { d = None; } -// if e == nil { e = new(List); } -// if f == nil { f = new(Dict); } -// +// // def myfunc(d=None, e=[], f={}) +// var ( +// d Value +// e *List +// f *Dict +// ) +// err := UnpackArgs("myfunc", args, kwargs, "d?", &d, "e?", &e, "f?", &f) +// if d == nil { d = None; } +// if e == nil { e = new(List); } +// if f == nil { f = new(Dict); } func UnpackArgs(fnname string, args Tuple, kwargs []Tuple, pairs ...interface{}) error { nparams := len(pairs) / 2 var defined intset diff --git a/starlarkstruct/struct.go b/starlarkstruct/struct.go index ea2b1f63..2282d7fb 100644 --- a/starlarkstruct/struct.go +++ b/starlarkstruct/struct.go @@ -4,7 +4,6 @@ // Package starlarkstruct defines the Starlark types 'struct' and // 'module', both optional language extensions. -// package starlarkstruct // import "go.starlark.net/starlarkstruct" // It is tempting to introduce a variant of Struct that is a wrapper @@ -36,10 +35,9 @@ import ( // // An application can add 'struct' to the Starlark environment like so: // -// globals := starlark.StringDict{ -// "struct": starlark.NewBuiltin("struct", starlarkstruct.Make), -// } -// +// globals := starlark.StringDict{ +// "struct": starlark.NewBuiltin("struct", starlarkstruct.Make), +// } func Make(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) { if len(args) > 0 { return nil, fmt.Errorf("struct: unexpected positional arguments")