only execute run "$@" if the script is not sourced

[meleu]

Request

The final script finishes with a run "$@" and that actually "runs the program".

It would be better if that call didn't happen when the script is being sourced.

Here's a suggestion (the explanation for the is_sourced detection is at the end of this post):

# checking if the file is being sourced
is_sourced() {
  (return 0 2> /dev/null)
}

# ...

initialize
is_sourced || run "$@"

I believe this solution has no effect on the usual way of calling the final script for an actual run, then generating the final code with that logic could be the default behavior. There's not even a need to implement it as a configuration option.

Motivation

The main motivation is because I usually source my .sh files with functions in order to "unit test" the functions.

It wasn't a problem in my usual workflow, where files sourcing other files is perfectly normal. But with bashly we can't/shouldn't source other files, as they all are going to be merged into the single generated script.

Being able to source the final script without actually running it would solve this problem, as I would be able to "unit test" my functions from there.

Another motivation is that sometimes I like to source my code in a new bash session and test my functions interactively (kinda like a rails console session)

---

explaining the is_sourced solution

This technique was taken from this StackOverflow answer.

(return 0 2>/dev/null) && sourced=1 || sourced=0

The return help message explains most of what's happening:

$ help return
return: return [n]
    Return from a shell function.

    Causes a function or sourced script to exit with the return value
    specified by N.  If N is omitted, the return status is that of the
    last command executed within the function or script.

    Exit Status:
    Returns N, or failure if the shell is not executing a function or script.

But let's elaborate it...

Bash allows return statements only from functions and, in a script's top-level scope, only if the script is sourced. If return is used out of these conditions, it fails (non-zero exit code) and an error message is emitted.

Let's check what happens in an interactive session.

$ return 0
bash: return: can only `return' from a function or sourced script
$ echo $?
2

Explaining the (return 0 2>/dev/null):

• executes return in a subshell
• suppresses the error message
• afterwards the exit code indicates whether the script was sourced or not

The use of a ( parenteses ) to create a subshell is necessary, because executing return in the top-level scope of a sourced script would exit the script.

We need to explicitly use 0 as the return operand, because omitting it can produce incorrect result if the last command on the user's shell has a non-zero return value.

[DannyBen]

Why not this:

if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  initialize
  run "$@"
fi

[DannyBen]

Well. As much as I appreciate the deep dive into fine tuning bashly, I feel this is an edge case of an edge case. In simple terms, I do not want to let the tail wag the dog, and have the edge cases dictate how the script looks.

Although I am testing my own bashly-generated scripts without sourcing them, I can relate to the need to sometimes source them for testability.

I am not comfortable with adding the condition you mentioned.
However - perhaps allowing a way for the user to override how this looks? In the same way we have a header.sh hook, have a footer.sh or execute.sh hook?

[meleu]

I feel this is an edge case of an edge case.

Are you referring to the "calling bash script-in-path.sh" situation?

I agree that this is an extreme edge case.

I also agree that my proposed solution looks hacky (not very intention revealing).

If you use the solution you brought (comparing with [[ "${BASH_SOURCE[0]}" == "${0}" ]]) as the default, with no need to add more complexity for bashly users, that would be awesome!

---

P.S.: when I talk about "no need to add more complexity for bashly users" I want to prevent this scenario:

• add another custom .sh file to be hooked into the final script
• explain to the user that such file is the only one whose the code won't be wrapped in a function

IMO this is not good, as it increases the cognitive load (more details to keep in mind).

[DannyBen]

Yes, I agree that if we can avoid taking the long route to a solution, it is preferred.

The question is - can we be 100% certain that the BASH_SOURCE condition will not have adverse effects?

[meleu]

can we be 100% certain that the BASH_SOURCE condition will not have adverse effects?

Well, the edge case of an edge case I mentioned above is a situation that already shows that 100% is impossible.

Trying to explain the scenario with less words:

• myscript is in some dir of the $PATH
• current working directory has no myscript file
• user call bash myscript (just the filename, no path given) and expects it to be executed
  • the script won't run, as it's going to be erroneously considered as sourced

[DannyBen]

That is a "non use case" in my view.
If it is in the path, you are expected to run it without a bash ... prefix.
If it is in the current dir, you may want to run it with a bash ... prefix - but this is also not a common case - since your generated CLI is called "myscript" and not "myscript.sh".

Unless I missed something, I am fine with considering this specific case out of scope.

[DannyBen]

Also - if there is a small doubt that some users may want the current behavior - we can add a setting for it, with a sensible default:

# settings.yml
enable_sourcing: always  # always | production | development | never

I feel like this goes well with the enable_* environment tweaks, as you may want to only enable it in development for your unit tests, and build a clean version without it to production.

What do you think?

[DannyBen]

Hmm. You have a good point, but this feels weird. Either the script runs something, or it doesn't.

Isn't it an expected and acceptable requirement to have unit tests, or other scripts that source it to initialize it if they need the initialization functionality? On the other hand, most things wont work without first calling initialize.....

Now both options feel smelly to me...

Just for reference, if we do it your way, this is what I see:

initialize
[[ "${BASH_SOURCE[0]}" == "${0}" ]] && run "$@"   # only in development

In other languages - when you include something you don't expect it to run any code.
It is a strong guideline for me in making decisions about bashly features.

---

Also, if we examine my way for a minute, it will simply mean that in your unit tests, you will have something like:

source thescript
initialize

# your tests here

which I feel good about - it is intentional, clear and concise.

No?

[DannyBen]

putting the initialize call inside the "if is-sourced" block would ...

Just correction: It is if NOT sourced then initialize and run

[meleu]

I think my bias here is because I usually put the global definitions at top-level scope (outside functions).

But as bashly provide the possibility to customize the initialization via src/initialize.sh, that could lead to weird situations when sourcing...

Therefore, my current opinion is that your original proposal is a good solution:

# if enable_sourcing evaluates to true
if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
  initialize
  run "$@"
fi

Then I explicitly call initialize in my tests. 👍

Thank you for your patience. ❤️

[DannyBen]

I think my bias here is because I usually put the global definitions at top-level scope (outside functions) the definitions.

Understood, but this is more of a "dirty" acceptable standard in scripting.
With this new feature, bashly will generate scripts that are can be completely encapsulated by functions (well - except the bash 3 bouncer...) - which is more in line with how programming in other languages is expected to look like, especially when testability is a priority.

[DannyBen]

Tracked in issue #596.

Thanks for the thoughtful discussion.

[meleu]

Implemented via #597