Nim tutorial says exceptions should not be used for file open errors yet readFile/readLines does just that

[TomasHubelbauer]

I'm new to Nim and I'm trying to make sense of some basic functionality and the various documentation and tutorials available. Right now I'm reading the Nim tutorial:
https://nim-lang.org/docs/tut2.html#exceptions

On the topic of exceptions, it says they should not be used in cases which are not exception, like a failure to open a file (it may not exist - a common occurence). I was vigorously nodding along while reading this, but when I tried to use readFile and readLines I found they do just this - raise an exception if a file does not exist.

I've verified this is truly an exception being thrown by wrapping the read call in try-except:

try:
  echo readFile("existent.not")
except IOError:
  echo "no file"

This successfully catches the exception and redirects control flow. To me this seems as a suboptimal way to handle the file not existing - but I don't know a better way to check which does not involve opening the file handle, check it and then reading the file as a stream. I want to use a simple I/O helper method to just slurp up a small text file into memory in one go. Is there one such?

Can either the tutorial be updated to remove the sentence about file read not throwing when they clearly do? I except that's more likely to happen than the behavior of the readFile/readLines methods changing to not be throwing?

I'll be happy to update the tutorial myself, just directly me to instructions on how to do it. That's assuming it is open source.

Example

echo readFile("existent.not")
# An exception is raised!

Additional Information

$ nim -v
Nim Compiler Version 1.4.0 [MacOSX: amd64]
Compiled at 2020-10-17
Copyright (c) 2006-2020 by Andreas Rumpf

active boot switches: -d:release -d:nimUseLinenoise

[Deleted user]

You can use open if you don't want exceptions:

var f: File
if f.open("existent"):
  echo f.readAll()

[TomasHubelbauer]

Do I need to close the handle manually down the line or is it cool to let it dangle in Nim, will it close it for me based on some heuristics? Sorry, not familiar enough with Nim to know better yet. I'm trying to avoid dealing with file handles at this stage for precisely this reason.

[Deleted user]

@TomasHubelbauer oh right, you need to close it manually for now :) But it's planned to add automatic closing of files

[TomasHubelbauer]

Thanks for letting me know! I'll stick to using try-except for control flow for now but I'm excited to learn about automatic handle closing in the future and I'll keep an eye on the changelog for when it comes.

[timotheecour]

Maybe reopen and fix the docs?

[TomasHubelbauer]

Could a link to each doc page be added to the docs site which would take one to the GitHub file for the page? I think the docs are in nim/website? But I don't feel like digging through the file list to find out. Also, how should we fix the docs? Should the mention of file opens not throwing be removed?

[timotheecour]

every generated html page should have a Source and Edit link; currently only symbols have those (eg: https://nim-lang.github.io/Nim/os.html#ReadEnvEffect). PR welcome to fix that; we can help; see:
https://nim-lang.github.io/Nim/docgen.html#related-options-see-source-switch
and see where seesrc is used in the code and nimdoc.cfg

This shouldn't be too complicated, but would be a very welcome PR

how should we fix the docs? Should the mention of file opens not throwing be removed?

yes, IMO (that should be a easy PR)

I think the docs are in nim/website?

I wouldn't worry about those, we just need to fix docgen so that source+edit links are generated not just for symbols but also at top-level of each page.

[TomasHubelbauer]

I apologize for not getting any of this, could you please break this down for me a bit more? You say the symbol pages have links to source, but those appear to be links to the source code of the symbols - and the edit link seems to be useful to make a quick PR?

I don't get where I should flip the switch to enable the generation of these across the docs site, not just the symbols. Further you say I shouldn't worry about nim/website, but isn't that exactly where the docs site is hosted from? Shouldn't that the the place where I would need to apply the setting to enable the source/edit links for all pages?

But even then, the page I linked to is a tutorial, not a documentation/reference page for any given symbol. What you're talking about seems to be the generated reference site, but I'm on about the documentation site and a tutorial on it.

Thanks for your patience!

[timotheecour]

I don't get where I should flip the switch to enable the generation of these across the docs site, not just the symbols

it's more complicated than flipping a switch, but also not very complicated, it involves digging into compiler/docgen.nim sources a bit and following the pointers I gave above.

EDIT: did it here: #15642

I shouldn't worry about nim/website, but isn't that exactly where the docs site is hosted from

docs are generated from nim doc automatically after (almost) every commit and end up here https://nim-lang.github.io/Nim/lib.html ; on each release they're also copied to https://nim-lang.org/docs/lib.html so you only need to worry about the doc generation, the changes would propagate to nim website on the next release (but most people use https://nim-lang.github.io/Nim/lib.html since these docs are more up to date)

But even then, the page I linked to is a tutorial, not a documentation/reference page for any given symbol. What you're talking about seems to be the generated reference site, but I'm on about the documentation site and a tutorial on it.

same, the source is tut2.rst; that's the file that needs to be edited for correctness