Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Remove cast_xyz functions from docs #1528

Merged
merged 1 commit into from
Jun 27, 2019
Merged

docs: Remove cast_xyz functions from docs #1528

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
124 changes: 63 additions & 61 deletions ast/builtins.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -67,8 +67,10 @@ var DefaultBuiltins = [...]*Builtin{
ArrayConcat,
ArraySlice,

// Casting
// Conversions
ToNumber,

// Casts (DEPRECATED)
CastObject,
CastNull,
CastBoolean,
Expand Down Expand Up @@ -522,7 +524,7 @@ var ArraySlice = &Builtin{
}

/**
* Casting
* Conversions
*/

// ToNumber takes a string, bool, or number value and converts it to a number.
Expand All @@ -543,65 +545,6 @@ var ToNumber = &Builtin{
),
}

// CastArray checks the underlying type of the input. If it is array or set, an array
// containing the values is returned. If it is not an array, an error is thrown.
var CastArray = &Builtin{
Name: "cast_array",
Decl: types.NewFunction(
types.Args(types.A),
types.NewArray(nil, types.A),
),
}

// CastSet checks the underlying type of the input.
// If it is a set, the set is returned.
// If it is an array, the array is returned in set form (all duplicates removed)
// If neither, an error is thrown
var CastSet = &Builtin{
Name: "cast_set",
Decl: types.NewFunction(
types.Args(types.A),
types.NewSet(types.A),
),
}

// CastString returns input if it is a string; if not returns error.
// For formatting variables, see sprintf
var CastString = &Builtin{
Name: "cast_string",
Decl: types.NewFunction(
types.Args(types.A),
types.S,
),
}

// CastBoolean returns input if it is a boolean; if not returns error.
var CastBoolean = &Builtin{
Name: "cast_boolean",
Decl: types.NewFunction(
types.Args(types.A),
types.B,
),
}

// CastNull returns null if input is null; if not returns error.
var CastNull = &Builtin{
Name: "cast_null",
Decl: types.NewFunction(
types.Args(types.A),
types.NewNull(),
),
}

// CastObject returns the given object if it is null; throws an error otherwise
var CastObject = &Builtin{
Name: "cast_object",
Decl: types.NewFunction(
types.Args(types.A),
types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)),
),
}

/**
* Regular Expressions
*/
Expand Down Expand Up @@ -1439,6 +1382,65 @@ var NetCIDROverlap = &Builtin{
),
}

// CastArray checks the underlying type of the input. If it is array or set, an array
// containing the values is returned. If it is not an array, an error is thrown.
var CastArray = &Builtin{
Name: "cast_array",
Decl: types.NewFunction(
types.Args(types.A),
types.NewArray(nil, types.A),
),
}

// CastSet checks the underlying type of the input.
// If it is a set, the set is returned.
// If it is an array, the array is returned in set form (all duplicates removed)
// If neither, an error is thrown
var CastSet = &Builtin{
Name: "cast_set",
Decl: types.NewFunction(
types.Args(types.A),
types.NewSet(types.A),
),
}

// CastString returns input if it is a string; if not returns error.
// For formatting variables, see sprintf
var CastString = &Builtin{
Name: "cast_string",
Decl: types.NewFunction(
types.Args(types.A),
types.S,
),
}

// CastBoolean returns input if it is a boolean; if not returns error.
var CastBoolean = &Builtin{
Name: "cast_boolean",
Decl: types.NewFunction(
types.Args(types.A),
types.B,
),
}

// CastNull returns null if input is null; if not returns error.
var CastNull = &Builtin{
Name: "cast_null",
Decl: types.NewFunction(
types.Args(types.A),
types.NewNull(),
),
}

// CastObject returns the given object if it is null; throws an error otherwise
var CastObject = &Builtin{
Name: "cast_object",
Decl: types.NewFunction(
types.Args(types.A),
types.NewObject(nil, types.NewDynamicProperty(types.A, types.A)),
),
}

// Builtin represents a built-in function supported by OPA. Every built-in
// function is uniquely identified by a name.
type Builtin struct {
Expand Down
17 changes: 8 additions & 9 deletions docs/content/language-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,24 +123,23 @@ The following table shows examples of how ``glob.match`` works:
| ``output := glob.match(""{cat,bat,[fr]at}", [], "rat")`` | ``true`` | A glob with pattern-alternatives matchers. |
| ``output := glob.match(""{cat,bat,[fr]at}", [], "at")`` | ``false`` | A glob with pattern-alternatives matchers. |

### Conversions

| Built-in | Description |
| --- | --- |
| <span class="opa-keep-it-together">``output := to_number(x)``</span> | ``output`` is ``x`` converted to a number. `null` is converted to zero, `true` and `false` are converted to one and zero (respectively), `string` values are interpreted as base 10, and `numbers` are a no-op. Other types are not supported. |

### Types

| Built-in | Description |
| ------- |-------------|
| <span class="opa-keep-it-together">``output := to_number(x)``</span> | ``output`` is ``x`` converted to a number |
| <span class="opa-keep-it-together">``output := is_number(x)``</span> | ``output`` is ``true`` if ``x`` is a number |
| <span class="opa-keep-it-together">``output := is_string(x)``</span> | ``output`` is ``true`` if ``x`` is a string |
| <span class="opa-keep-it-together">``output := cast_string(x)``</span> | ``output`` is ``x`` cast to a string |
| <span class="opa-keep-it-together">``output := is_boolean(x)``</span> | ``output`` is ``true`` if ``x`` is a boolean |
| <span class="opa-keep-it-together">``output := cast_boolean(x)``</span> | ``output`` is ``x`` cast to a boolean |
| <span class="opa-keep-it-together">``output := is_array(x)``</span> | ``output`` is ``true`` if ``x`` is an array |
| <span class="opa-keep-it-together">``output := cast_array(x)``</span> | ``output`` is ``x`` cast to an array |
| <span class="opa-keep-it-together">``output := is_set(x)``</span> | ``output`` is ``true`` if ``x`` is a set |
| <span class="opa-keep-it-together">``output := cast_set(x)``</span> | ``output`` is ``x`` cast to a set |
| <span class="opa-keep-it-together">``output := is_object(x)``</span> | ``output`` is ``true`` if ``x`` is an object |
| <span class="opa-keep-it-together">``output := cast_object(x)``</span> | ``output`` is ``x`` cast to an object |
| <span class="opa-keep-it-together">``output := is_null(x)``</span> | ``output`` is ``true`` if ``x`` is null |
| <span class="opa-keep-it-together">``output := cast_null(x)``</span> | ``output`` is ``x`` cast to null |
| <span class="opa-keep-it-together">``output := type_name(x)``</span> | ``output`` is the type of ``x`` |

### Encoding
Expand Down Expand Up @@ -201,11 +200,11 @@ If there are any unrecognized constraints then the token is considered invalid.
> Multiple calls to the `time.now_ns` built-in function within a single policy
evaluation query will always return the same value.

Timezones can be specified as
Timezones can be specified as

* an [IANA Time Zone](https://www.iana.org/time-zones) string e.g. "America/New_York"
* "UTC" or "", which are equivalent to not passing a timezone (i.e. will return as UTC)
* "Local", which will use the local timezone.
* "Local", which will use the local timezone.

Note that the opa executable will need access to the timezone files in the environment it is running in (see the [Go time.LoadLocation()](https://golang.org/pkg/time/#LoadLocation) documentation for more information).

Expand Down
6 changes: 6 additions & 0 deletions topdown/casts.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ func builtinToNumber(a ast.Value) (ast.Value, error) {
return nil, builtins.NewOperandTypeErr(1, a, "null", "boolean", "number", "string")
}

// Deprecated in v0.13.0.
func builtinToArray(a ast.Value) (ast.Value, error) {
switch val := a.(type) {
case ast.Array:
Expand All @@ -49,6 +50,7 @@ func builtinToArray(a ast.Value) (ast.Value, error) {
}
}

// Deprecated in v0.13.0.
func builtinToSet(a ast.Value) (ast.Value, error) {
switch val := a.(type) {
case ast.Array:
Expand All @@ -60,6 +62,7 @@ func builtinToSet(a ast.Value) (ast.Value, error) {
}
}

// Deprecated in v0.13.0.
func builtinToString(a ast.Value) (ast.Value, error) {
switch val := a.(type) {
case ast.String:
Expand All @@ -69,6 +72,7 @@ func builtinToString(a ast.Value) (ast.Value, error) {
}
}

// Deprecated in v0.13.0.
func builtinToBoolean(a ast.Value) (ast.Value, error) {
switch val := a.(type) {
case ast.Boolean:
Expand All @@ -78,6 +82,7 @@ func builtinToBoolean(a ast.Value) (ast.Value, error) {
}
}

// Deprecated in v0.13.0.
func builtinToNull(a ast.Value) (ast.Value, error) {
switch val := a.(type) {
case ast.Null:
Expand All @@ -87,6 +92,7 @@ func builtinToNull(a ast.Value) (ast.Value, error) {
}
}

// Deprecated in v0.13.0.
func builtinToObject(a ast.Value) (ast.Value, error) {
switch val := a.(type) {
case ast.Object:
Expand Down