Syntax errors in docs code examples about elvish HOT 8 CLOSED

The first documentation problem involving try... else... was noted in #1734, but it's great that a new user has noticed the same issue. That new users have noticed the same issue makes it even more important to improve that aspect of the documentation.

from elvish.

In that case, I'll raise a PR to fix the try... else... example in the docs.

Perhaps it would have been better for me to create two separate issues, as I feel the ?(...) docs example and explanation are fundamentally at odds with each other.

The explanation

Note: Exception captures do not affect the output of the code chunk. You can combine output capture and exception capture:

doesn't align with the code example

var output = (var error = ?(commands-that-may-fail))

Would it be better for me to close this issue, create a PR to address the existing issue #1734, then create a separate issue for discussion of the exception capture docs?

from elvish.

Here is a PR to address #1734

from elvish.

As an observation, the syntax for try/else/finally is a bit confusing as a new user.

The syntax implies the else happens instead of the try

Also, is there a need for such a construct?

For example, instead of

try {
  cat log-file > /tmp/log-snapshot
} else {
  aws s3api put-object --bucket logs --key logs/latest --body /tmp/log-snapshot
} finally { 
  rm -f /tmp/log-snapshot
}

would it not be sufficient to simply do

try {
  cat log-file > /tmp/log-snapshot
  aws s3api put-object --bucket logs --key logs/latest --body /tmp/log-snapshot
} finally { 
  rm -f /tmp/log-snapshot
}

If there is a valid use case for try/else/finally I'd be happy to add it to the above PR

If try/else/finally doesn't make sense, perhaps it would be better to make else conditional on the presence of catch?

from elvish.

As far as I can tell, an else block without both a catch block and a finally block has no purpose. If there is no catch, you can merge the try and else blocks, and if there is no finally, you just put the content of the else after the try statement. (And if there is neither a catch nor a finally block, the trystatement is a syntax error anyhow, so the point is moot. But that raises the question whether an else block without both catch and finally should be a syntax error too.)

from elvish.

I forgot to address this one:

The syntax implies the else happens instead of the try

As in if/else, you mean? The intent is that the else happens instead of the catch when there is no error, but if there is no catch block, it does indeed get a bit confusing. That's another argument for actually restricting the syntax to avoid this problem.

from elvish.

Thanks for clarifying

@xiaq said the same thing

#1782 (comment)

An else doesn't make sense in the absence of a catch

from elvish.

As far as I can tell, an else block without both a catch block and a finally block has no purpose. If there is no catch, you can merge the try and else blocks, and if there is no finally, you just put the content of the else after the try statement. (And if there is neither a catch nor a finally block, the trystatement is a syntax error anyhow, so the point is moot. But that raises the question whether an else block without both catch and finally should be a syntax error too.)

In version 0.21.0 an else without either a catch or finally is an error, which is what prompted the issue. =)

Thanks for the clarification though. I'm super excited about the future of Elvish

from elvish.