rename sta::source to sta::include to allow use of tcl source

[donn]

• create new global stack, ::_sta_file_stack, to keep track of evaluated files (include and source)
• rename sta::source to sta::include, allowing the original tcl source (which behaves differently, including inheriting the caller's scope) to be used
• create new thin wrapper for tcl source as sta::source - all it does is push to and pop from ::_sta_file_stack
• update sta_error, sta_warn to inspect the stack and alter behavior based on whether the current file is sourced or included

Original PR body follows:

---

• add new global variable, ::sta_scoped_source that if set to 1, causes all sourced files to be evaluated at the scope of the calling function instead of the top level (default 0). read_sdc will always be evaluated at the top-level, however.
• ignore early returns when sourcing files - tcl return is supposed to work when sourcing files. see https://www.tcl-lang.org/man/tcl8.6/TclCmd/return.htm for more info

---

I have chosen to make it opt-in behavior out of an excess of caution. The ~/.sta issue could technically be resolved by upleveling sourceTclFile, but that may have unforeseen consequences. Fortunately, it's not a huge ask to ask users to set ::sta_scoped_source to 1 before package require statements.

Resolves #202

[CLAassistant]

All committers have signed the CLA.

[donn]

sorry - found another issue with package require

EDIT: So this is annoying but early returns from a sourced file also have to be emulated for tcllib to work. I'll see what can be done about that.

[akashlevy]

Any chance you can resolve #204 while you are at it? Would greatly appreciate it @donn

[donn]

Hi Akash- will try, pun not intended, but I really doubt I can because this whole thing is already enough of a Tcl scoping nightmare. I can't just include the forward-compat code either as it has no license.

[akashlevy]

If you can use catch instead of try, that would be awesome

[akashlevy]

This is addressed in #206 so no need to address @donn, thanks anyways

[donn]

@jjcherry56 Should be ready now.

[jjcherry56]

I am not a fan of this approach.
The redefinition of source dates back 20 years to match the behavior of another tool.
I think it would make more sense to remove the code that redefines source and define a new command "read_cmds" (without the unused -verbose option) based on the existing implementation.

[donn]

That... would be my preferred approach too. I just assumed you wouldn't want to break existing code.

[donn]

@jjcherry56 Done.

[jjcherry56]

I tried this myself a few days ago. I decided "include" makes more sense than "read_cmds".
The problem is that using the builtin source (which happens the most) sta_errror/warn do not report the filename or line number, so it isn't this simple. I stopped there because I have higher priority issues to deal with.

[donn]

@jjcherry56 So I implemented a solution to this that works as follows:

There's now an ::_sta_file_stack. This stack is composed of tuples of:

• either include or source
• the normalized filename

Both sta::include and sta::source add the file currently under processing to the stack.

sta::warn and sta::error peek the top element of the stack, and if it's an include, use the previous behavior.

If it's a source, however, the frame stack is inspected to return the line number of the lowest stack frame in the sourced file. This is to emulate the behavior of how include's line numbers work as closely as possible. I added a test for this behavior.

[jjcherry56]

what I had in mind was NOT redefining source and making include set the info file/line properties like source does so it has the same behavior and modifying sta_error/warn to use the info file/line instead of variables or stack

[donn]

That'd require include to be partially implemented in C so it can create a new stack frame (I'm unaware of a way to do that in Tcl) -- sadly though, I'd have to tackle that another time as that is far more involved.