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

Update intro examples #177

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
+45 −13
Open

Update intro examples #177

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
492f950
Update intro examples
TristonianJones Jan 26, 2021
0016c7f
Update langdef.md references to 'size' to indicate it should be used …
TristonianJones Feb 2, 2021
e46f2a7
Updated the docs to indicate the full set of size() overloads
TristonianJones Mar 10, 2021
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
8 changes: 4 additions & 4 deletions doc/intro.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,8 +30,8 @@ example, given an instance of the `Account` type assigned to the variable

```proto
has(account.user_id) || has(account.gaia_id) // true if either one is set
size(account.emails) > 0 // true if emails is non-empty
matches(account.phone_number, "[0-9-]+") // true if number matches regexp
account.emails.size() > 0 // true if emails is non-empty
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please add the 4 receiver-style size() declarations to the list of standard definitions.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've basically replaced the global existing definitions with the receiver-style ones. That's been the preference internally for quite some time, but I didn't realize this wasn't reflected publicly.

account.phone_number.matches("[0-9-]+") // true if number matches regexp
```

CEL expressions support most operators and functions one would expect when
Expand Down Expand Up @@ -60,7 +60,7 @@ doesn't have a matching protocol buffer type. Within CEL, these objects support
the same accesses and functions as protocol buffer types:

```proto
has(account.properties.id) && size(account.properties.id) > 0
has(account.properties.id) && account.properties.id.size() > 0
```

When the expression `account.properties` is evaluated, CEL will automatically
Expand All @@ -85,7 +85,7 @@ citizens of CEL:
```proto
has(account.properties.id)
&& (type(account.properties.id) == string
|| type(account.properties.id) == list(string))
|| type(account.properties.id) == list)
```

CEL's default type checker deals with a mixture of dynamic and static typing;
Expand Down
50 changes: 41 additions & 9 deletions doc/langdef.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -632,7 +632,7 @@ A CEL expression is parsed and evaluated in the scope of a particular protocol
buffer package, which controls name resolution as described above, and a binding
context, which binds identifiers to values, errors, and functions. A given
identifier has different meanings as a function name or as a variable, depending
on the use. For instance in the expression `size(requests) > size`, the first
on the use. For instance in the expression `requests.size() > size`, the first
`size` is a function, and the second is a variable.

The CEL implementation provides mechanisms for adding bindings of variable names
Expand Down Expand Up @@ -914,7 +914,7 @@ size of the inputs.
cost of `O(P * I)`, and see below.
* Eliminating all of the above and using only default-cost functions, plus
aggregate literals, time and space are limited `O(P * I)`.
A limiting time example is `size(x) + size(x) + ...`.
A limiting time example is `x.size() + x.size() + ...`.
A limiting time and space example is `[x, x, ..., x]`.

Note that custom function will alter this analysis if they are more expensive
Expand Down Expand Up @@ -942,31 +942,31 @@ specified by the following overloads:
size
</th>
<td>
(string) -> int
string.() -> int
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I'm okay marking the function-style version as "deprecated", but I don't think it's okay to just remove it. Anyone attempting to implement a compatible CEL implementation will need to provide the function-style versions for the foreseeable future, so it ought to be in the language spec.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ugh, now it's a confusing example because we're not listing the full set of overloads. Unfortunately, the other functions with multiple overloads are either:

  • Operators, which introduce an unnecessary complication.
  • Conversion functions, which we single out in their description as being different.
  • The get*() functions on timestamps and durations, but we're going to deprecate them on the durations.
  • Other oddballs like dyn().

So consider whether there's a better example to use here, but I'm okay with just the receiver-style size functions if you don't think there's a better alternative.

</td>
<td>
string length
number of unicode codepoints in the string
</td>
</tr>
<tr>
<td>
(bytes) -> int
bytes.() -> int
</td>
<td>
bytes length
</td>
</tr>
<tr>
<td>
(list(A)) -> int
list(A).() -> int
</td>
<td>
list size
</td>
</tr>
<tr>
<td>
(map(A, B)) -> int
map(A, B).() -> int
</td>
<td>
map size
Expand Down Expand Up @@ -2152,14 +2152,30 @@ See [cel-go/issues/9](https://github.com/google/cel-go/issues/9).
</td>
</tr>
<tr>
<th rowspan="4">
<th rowspan="8">
size
</th>
<td>
string.() -> int
</td>
<td>
number of unicode codepoints in the string
</td>
</tr>
<tr>
<td>
(string) -> int
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Mark the function-style overload as "deprecated", here and below. (Boy, I wish we had adapted Uniform Function Call Syntax and we wouldn't have had to worry about any of this.)

</td>
<td>
string length
number of unicode codepoints in the string
</td>
</tr>
<tr>
<td>
bytes.() -> int
</td>
<td>
bytes length
</td>
</tr>
<tr>
Expand All @@ -2170,6 +2186,14 @@ See [cel-go/issues/9](https://github.com/google/cel-go/issues/9).
bytes length
</td>
</tr>
<tr>
<td>
list(A).() -> int
</td>
<td>
list size. Time cost proportional to the length of the list.
</td>
</tr>
<tr>
<td>
(list(A)) -> int
Expand All @@ -2178,6 +2202,14 @@ See [cel-go/issues/9](https://github.com/google/cel-go/issues/9).
list size. Time cost proportional to the length of the list.
</td>
</tr>
<tr>
<td>
map(A, B).() -> int
</td>
<td>
map size. Time cost proportional to the number of entries.
</td>
</tr>
<tr>
<td>
(map(A, B)) -> int
Expand Down