Custom Libraries Template

[DannyBen]

This discussion started in #674.

A Custom Libraries Template was created here:
https://github.com/bashly-framework/custom-libs-template

The documentation was updated accordingly.

Thoughts are welcome.

[DannyBen]

@meleu - you mentioned you have some libraries that can be suitable for public use, in our soon-to-be-born userlib repo.

Can you list some examples? Perhaps paste code for one of them?
I want to see if we have something to start with, before we commit to this path.

[meleu]

Oh, I was actually asking just for the template... 😅

And the one you created is pretty neat. 👌

Anyways, I'll share my code once I find sometime to organize it. 🧑‍💻

---

By the way, I have another question about custom libraries:

Would you say that having each function in their own file is a recommended practice?

I noticed you do it this way and I wonder if it's just your way to organize your code or if there's another reason.

I'm assuming that a benefit of this practice is that users can easily remove the unused functions. So, the code doesn't get added into the final script.

If my assumption is correct, maybe we could have such instructions in the template's README.

[DannyBen]

Would you say that having each function in their own file is a recommended practice?

This is a matter of choice, and is probably going to be different for each user, depending from which programming language they are coming from.

Personally, I see no reason not to place each in a single function, as it is easier for me to quickly "fuzzy search" the function name in my Sublime, and it opens the file for editing.

Other people may prefer grouping several functions together, like src/lib/docker-functions.sh.

maybe we could have such instructions in the template's README

Yes, I think it can't hurt.
A comment like this is placed in the default sample you get when running bashly add lib

## Add any function here that is needed in more than one parts of your
## application, or that you otherwise wish to extract from the main function
## scripts.
##
## Note that code here should be wrapped inside bash functions, and it is
## recommended to have a separate file for each function.
##
## Subdirectories will also be scanned for *.sh, so you have no reason not
## to organize your code neatly.
##
sample_function() {
  echo "it works"
}

[DannyBen]

After coffee, my head is clearer, so to add to the above answer:

Oh, I was actually asking just for the template... 😅

This makes sense. So I will add to the template README something to encourage users to share their "cutom lib" repo.

Would you say that having each function in their own file is a recommended practice?

You are right to ask that. The example I have provided is in fact more suitable to be in one "prompts.sh" file - but I wanted to demonstrate how to add two files in the libraries.yml.

In general - I go by "single concern, single file".
I will document it in bashly.dev - as I want a single point of docs.

[DannyBen]

Updated docs:
https://bashly.dev/advanced/lib-source/

Updated header:
https://github.com/bashly-framework/custom-libs-template

[meleu]

Months after this thread was opened I finally had sometime to start playing with custom libraries...

Here's the repo: https://github.com/meleu/bashly-libs

The first lib I created is the logs, because I always use some sort of log_info, log_warn, log_error in my Bash programs.

The actual code is here.

Now I have a question for @DannyBen: What should I do if I want to explicitly mention an "official" lib as a dependency of my custom lib?

Example:
I want to add colors to my log_* functions. Instead of writing code to handle this I would like to use the Bashly's colors lib.

I know that I can guide the users to install colors in order to use logs, the question is just: is there a way to make this installation automatic? If not, do you think this is a nice feature to have?

(tbh I think this would open the gates for all sorts of problems related to dependency management, then I completely understand if the answer is "no")

This is similar to the config & ini libs (config depends on ini, then when the user installs config, ini is also automatically installed), with the difference that logs & colors are in different repositories.

[DannyBen]

Heh. You have hit multiple nails on their head.

1. I also have a standard log file I am using (example)
2. Requiring another lib as a dependency is definitely a scenario that is not currently handled well
3. The config library that brings the ini file with it (as can be seen in the libraries index manifes) is not the best solution
4. The only way to currently state these dependencies, is to ask the user to run bashly add ... - which is far from ideal

The truth is that I sometimes view bashly add * as a candidate for removal.
It will never have all the libraries that bash users need, and it brings quite a lot of churn to the code.
The addition of "custom library location" is something that I doubt anybody uses - or at least I think it has no more than 5 users.

So whenever a new enhancement is raised for this feature, I go back to thinking: should this be enhanced, or eliminated.

I don't have the answer.

I do think that if we all still think that the libraries bring more benefit than annoyances, then perhaps a lightweight "depends_on" option is a good idea.

[DannyBen]

If we do think about adding a dependencies definition, I would consider something like this for the syntax:

# libraries.yml
config:
  help: ...
  files: [...]
  dependencies: [...]

where dependencies can be in one of these syntaxes:

# bring from *this* repository
dependencies: [ini, colors]

# bring from another repository
dependencies:
- name: log
  source: github:dannyben/bashly-lib  # support any URI supported by `bashly add --source`

# bring from the default repository
dependencies:
- name: colors
  source: bashly  # or some other token that represents the built in lib

[meleu]

So whenever a new enhancement is raised for this feature, I go back to thinking: should this be enhanced, or eliminated.

I have a third suggestion: just freeze it as it is! 😅

I mean, I really love how easy it is to add colors, stacktrace and validations to my bash programs. So, removing bashly add would mean copy'n'pasting code in order to have those solutions on my projects.

My opinion is that we should (at least in the short to medium term) embrace the "far from ideal" situation where lib creators must ask their users to bashly add their dependencies. Which means explicitly state that in the docs.

...

To be fair, this discussion made me think better and my (current) opinion is: given that we are talking about third-party code that will be executed directly in the shell, encouraging users to explicitly install dependencies is the wiser solution.

If you ever want to work on a depends_on option, I think it should just check if the mentioned dependency is available and list what's missing. Never install libs other than the one given to bashly add.

[DannyBen]

Which means explicitly state that in the docs.

I think the post_install_message is a good place for such mentions. And you can also use colors (the colsole syntax):

bashly/lib/bashly/libraries/libraries.yml

Lines 6 to 13 in 7786cd2

	post_install_message: |
	The colors library supports the g`NO_COLOR` standard out of the box.
	In case you wish to also enable automatic output of colors based on the
	terminal being interactive (TTY), call g`enable_auto_colors` in your
	g`src/initialize.sh`. You may run the following command to add this file:
	m`$ bashly add hooks`