Merge pull request #190 from yassinebenaid/dev

Rewrite documentation

docs/.vitepress/config.mts

@@ -26,6 +26,10 @@ export default defineConfig({
             collapsed: false,
             items: [
               { text: "Simple Commands", link: "/features/simple-commands" },
+              {
+                text: "Environment Files",
+                link: "/features/environment-files",
+              },
             ],
           },
           { text: "Contributing", link: "/contributing" },

docs/features/environment-files.md

@@ -0,0 +1,107 @@
+# Environment Files
+We have a first-class support for environment files. Known as [.env files](https://dotenvx.com/docs/env-file). This feature allows you
+to load environment variables from environment files and make them available as variables in the shell context.
+
+This is possible through the `envload` builtin command.
+
+## Quick Example
+You get started, define your variables in a `.env` file.
+_.env_:
+```sh
+KEY=value
+```
+
+Then use the `loadenv` builtin command:
+_script.sh_:
+```sh
+loadenv
+
+echo $KEY
+
+# value
+```
+
+## Environment file format
+We support the standard format of `.env` files. This includes simple keys, quoting, variable references and yaml format.
+
+```sh
+# comments are supported
+KEY=value # inline comments are supported too
+
+# quotes
+KEY="foo bar baz"
+KEY='foo bar baz'
+
+# reference other keys
+KEY=$KEY
+KEY=${KEY}
+KEY="$KEY"
+KEY="${KEY}"
+```
+
+### YAML format
+We also support the yaml format:
+```yaml
+# comments are supported
+KEY: value # inline comments are supported too
+
+# quotes
+KEY: "foo bar baz"
+KEY: 'foo bar baz'
+
+# reference other keys
+KEY: $KEY
+KEY: ${KEY}
+KEY: "$KEY"
+KEY: "${KEY}"
+```
+
+## Command Usage
+The command `loadenv` is very streightforward. When you do not pass any arguments. it will default to load `.env` file in current workin directory.
+
+```sh
+loadenv # loads .env in CWD
+```
+
+You can pass one or many file paths. In this case, the order of the files matters. Because files that come last override keys in files that come first.
+
+```sh
+loadenv file.env file2.yaml file3.env
+```
+
+### Exporting variables
+By default, the variables are only available in the current shell context. They are not exported to child processes. For example:
+
+_.env_:
+```sh
+NAME=bunster
+```
+
+In your script:
+
+```sh
+loadenv
+
+bash -c 'echo env:$NAME'
+echo var:$NAME
+```
+
+This will output:
+```txt
+env:
+var:bunster
+```
+
+To export them, you can use the `-X` flag to export them:
+```sh
+loadenv -X
+
+bash -c 'echo env:$NAME'
+echo var:$NAME
+```
+
+This will output:
+```txt
+env:bunster
+var:bunster
+```

docs/features/simple-commands.md

@@ -1,28 +1,98 @@
 # Simple Commands
-You may run simple commands just like in a regular shell. There is no difference between bash and bunster when it comes to running external commands.
-which are external programs accessible through the `$PATH` environment variable.
+Just like any other shell scripting language. Bunster allows you can run external progams.
 
-**Format**:
-```shell
+The format is as follows:
+```sh
 command-name [arguments...]
 ```
 
-The command name can be either a program name or a full relative or absolute path to the program. if the name is not a path, the program must be in `$PATH`.
+The `command-name` can be a full path to a program. or just the name of the binary. In that case, the binary must be accessible in `$PATH`.
+
+## Separator
+You can separate the command list by a new line. a semicolon `;`, an ampersand `&` or logical operators `&&` and `||`.
+
+```sh
+command argument argument
+command2 argument argument; command3 argument argument
+command4 argument argument;
+```
+
+we will talk more about ampersand `&` and logical operators later in the documentation.
 
 
 ## Quotes
+Quotes in bunster work the exact same as in bash.
 ### Double Quotes
-Quoting in bunster works the exact same as in bash. it preserves the literal value of the characters. for example:
+double quotes are used to preserve the literal meaning of tokens except the dollar sign `$`.
 
-```shell
-"command name" "arguments"
+```sh
+"command name" "foo bar"
 ```
 
-The dollar sign is an exception.
+This will run the comand `command name` and pass the argument `foo bar`.
 
+#### Dollar sign
+Dollar sign is a special token that is used for substitution. It does not lose it's meaning in double quotes:
 
-```shell
+```sh
 echo "$HOME"
 ```
 
-This will run the command `echo`. the first argument is the value of the variable `HOME`.
+This will run `echo`. and passes an argument which is the value of the `HOME` variable. (we will learn more about variables later).
+
+#### Escaping quotes
+You can escape double quotes within double quotes:
+
+```sh
+echo "\"foobar\""
+```
+
+This will run the command `echo` with the argument `"foobar"`.
+
+### Single Quotes
+Single quotes are also used to preserve the literal meaning of tokens. However, unlike double quotes, all tokens within single quotes loose their special meaning.
+Including the `$` dollar sign. And you cannot use escaping within single quotes
+
+```sh
+echo '$VAR\'
+```
+
+Runs the command `echo` with the argument `$VAR\`
+
+
+## Escaping
+Escaping is the same as in bash. you use the backslash `\` to preserve the literal meaning of the next token.
+The backslash it self is removed and the escaped token is treated literally.
+
+Newline `\n` is a special case. when you scape a newline. the newline is removed as well:
+
+```sh
+command\ name \
+    argument argument2
+```
+
+This will run the command `command name`. and pass the `argument` and `argument2` arguments.
+
+## Comments
+Comments in bunster are (as you may guess) the exact as in any other shell. Lines starting with `#` are ignored.
+Parts of lines that start with `#` are treated as comments as well and are ignored.
+
+```sh
+# full line comment
+command # inline comment
+```
+
+
+## Examples
+```sh
+echo foo bar
+
+echo "Hello World"
+
+echo 'Hello World'
+
+echo; echo
+
+echo \
+    foo bar
+```

docs/installation.md

@@ -7,11 +7,11 @@ We rely on [gofmt](https://pkg.go.dev/cmd/gofmt) provided by the [the Go toolcha
 code. This makes it easy to debug and/or to learn from. Additionally, We use [the Go compiler](https://go.dev/dl) to compile
 the code and generate the executable for you.
 
-::: info
+> [!info]
 The absence of [the Go toolchain](https://go.dev/dl) does not affect the working of **Bunster**. It's still going to work just fine.
 If you only care about the generated Go code, and don't want **Bunster** to automatically compile the exectuable for you.
 That is totally fine and you can go for it.
-:::
+
 
 ## Linux/Mac
 We have bash script that installs `bunster` and adds it to your `$PATH`.
@@ -26,9 +26,9 @@ The script will install bunster at `~/.local/bin/bunster` on linux. And `~/bin/b
 curl -f https://bunster.netlify.app/install.sh | GLOBAL=1 bash
 ```
 
-::: warning
-Do not trust scripts downloaded from the interne. take a look at the code before running it.
-:::
+> [!warning]
+> Do not trust scripts downloaded from the interne. take a look at the code before running it.
+
 
  ## Docker Image
 The easiest way to get **Bunster** is through our official [Docker Image](https://docs.docker.com/get-started/docker-concepts/the-basics/what-is-an-image/).
@@ -47,9 +47,9 @@ docker pull ghcr.io/yassinebenaid/bunster:v0.3.0
 ## Github Release
 You can get the latest version of `bunster` from [github releases](https://github.com/yassinebenaid/bunster/releases).
 
-::: warning
+> [!warning]
 Only `linux` and `macos` binaries are available at the moment. `windows` support is coming soon.
-:::
+
 
 ## Using Go
 If you already have [the Go toolchain](https://go.dev/dl) installed. You can use the `go install` command to get **Bunster** on your machine.
@@ -69,7 +69,6 @@ This will build the binary at `$HOME/go/bin/bunster`, if you want to make it acc
 mv $HOME/go/bin/bunster /usr/local/bin # you may need to use `sudo`.
 ```
 
-::: info
+> [!info]
 If you choose to install using `go install`. make sure that `$HOME/go/bin` is added to your `PATH`. If not yet, Please add
 `export PATH=$PATH:$HOME/go/bin` to one of your profile files. eg. *`~/.bashrc` if you're using `bash`, or `~/.zshrc` if you're using `zsh`*.
-:::

docs/introduction.md

@@ -26,4 +26,19 @@ makes you feel happy when writing shell scripts. a feeling that shells usually d
 
 <img src="./bunster.gif"/>
 
-[Learn more about the usage of bunster.](https://bunster.netlify.app)
+[Learn more about the usage of bunster.](/cli)
+
+## Bunster VS Bash
+We are not trying to compete with `bash`. Because unlike `bash`, bunster is not a shell. it is a programming language dedicated for scripting. `bash`
+has a scripting plan where you can write commands in scripts. but it's primary use case is interactively.
+
+Bunster is trying to take all good things from `bash`. Add more features to them and make them available in a simple and familiar programming language.
+
+
+## Why do we have a separate documentation ?
+We use the [bash reference](https://www.gnu.org/software/bash/manual/bash.html) as a source of truth. and so you can.
+Becasue we have a promise to keep compatibility with bash, you are free to refer to that manual
+for feature documentation for features supported by bunster.
+
+However, we decided to go with our own documentation so that we can focus on features that we support.
+Also, the bash reference keeps mentioning things that we have nothing to do with them. like interactive command line. Which is kind of confusing for our users.