Merge pull request #54 from yassinebenaid/dev

Bug fixes and docs improvment

Author: yassinebenaid

README.md

@@ -25,10 +25,11 @@ Technically speaking, **Bunster** is not a complete compiler, But rather a **Tra
 - **Different Shells support**: Bunster currently aims to be compatible `Bash` as a starting move. then other popular shells in future.
 - **Security**: as you may guess, humans cannot read machine code, so why not to compile your scripts to such format.
 - **Modules**: something shell scripts lack is a module system, people want to share their code to be used by others, but the infrastructure doesn't allow them. Well, **Bunster** introduces a module system that allow you to publish your scripts as a modules consumed by other users.
-- **Performance**: the shell (including bash, zsh ...etc) rely on forking to run your scripts, this means, if you have a script of 3 commands, the shell will have to fork it self 3 times to run each command. This allows the shell to play with file descriptors and other resouces freely. But adds a lot of performance overhead. **Bunster** runs your entire scripts in a single process. and uses [goroutines](https://go.dev/tour/concurrency/1) for background commands. **Bunster** even has its own file descripor system managed by it's runtime. this means less syscalls, thus, better performance.
+- **Performance**: You should't be concerned about performance that much, But at least scripts compiled by **Bunster** will not suffer to parse and interpret
+your scripts everytime you run them.
 
 > [!WARNING]
-> This project is in its early phase of development and is not yet ready for production. Not all features are implemented yet. But, plenty of them are already working. such as simple command invokation, redirections, environment variables and more.
+> This project is in its early phase of development and is not yet ready for production. Not all features are implemented yet. But, plenty of them are.[see what features are features so far](https://bunster.netlify.app/supported-features.html) such as simple command invokation, redirections, environment variables and more.
 
 ### Versionning
 **Bunster** follows [SemVer](https://semver.org/) system for release versionning. On each `v0.x.0` release, You would expect adding support for new features (can be new shell feature, improvement in the build process, some custom features ...etc.) . On each `v0.N.x` release, you would expect bug fixes and documentation enhancments.

docs/.vitepress/config.mts

@@ -10,13 +10,18 @@ export default defineConfig({
     nav: [
       { text: "Documentation", link: "/quick-start" },
       { text: "Installation", link: "/installation" },
+      { text: "Maintainers", link: "/maintainers" },
     ],
-
+    logo: "/logo.png",
+    search: {
+      provider: "local",
+    },
     sidebar: [
       {
         items: [
           { text: "Quick Start", link: "/quick-start" },
           { text: "Installation", link: "/installation" },
+          { text: "Supported Features", link: "/supported-features" },
         ],
       },
     ],
@@ -29,9 +34,17 @@ export default defineConfig({
       message: "Released under the GPLv3 License.",
       copyright: "Copyright © 2024-present Yassine Benaid",
     },
+    editLink: {
+      pattern:
+        "https://github.com/yassinebenaid/bunster/edit/master/docs/:path",
+    },
   },
   head: [
     ["link", { rel: "manifest", href: "/site.webmanifest" }],
     ["link", { rel: "icon", type: "image/x-icon", href: "/favicon.ico" }],
   ],
+  lastUpdated: true,
+  sitemap: {
+    hostname: "https://bunster.netlify.app",
+  },
 });

docs/maintainers.md

@@ -0,0 +1,29 @@
+---
+sidebar: false
+---
+
+<script setup>
+import { VPTeamMembers } from 'vitepress/theme'
+
+const members = [
+  {
+    avatar: 'https://www.github.com/yassinebenaid.png',
+    name: 'Yassine Benaid',
+    title: 'Creator',
+    links: [
+      { icon: 'github', link: 'https://github.com/yassinebenaid' },
+      { icon: 'linkedin', link: 'https://www.linkedin.com/in/yassinebenaid' },
+      { icon: 'reddit', link: 'https://www.reddit.com/user/yassinebenaid' }
+    ]
+  },
+]
+</script>
+
+# Maintainers
+**Bunster** is an open source project maintained and driven by the community, But we have a dedicated team
+that takes the final decision on contributions and feature requests. And keeps contact with the rest of the community to ensure a healthy and friendly
+environment for everyone.
+
+Say hello to our awesome team.
+
+<VPTeamMembers size="small" :members="members" />

docs/supported-features.md

@@ -0,0 +1,41 @@
+# Supported Features
+This page lists the features and syntax supported by **Bunster**. you must consider any feature that is not mentioned here
+as work-in-progress and as not-yet-supported.
+
+
+## Simple commands
+```shell
+command argument 'argument' "argument" $VARIABLE
+```
+
+## Redirections
+### Output redirection
+```shell
+command >file.txt >|file.txt >>file.txt &>file.txt &>>file.txt
+```
+### Input redirection
+```shell
+command <file.txt <<<"foo bar"
+```
+### File descriptor duplication and closing
+```shell
+command 2>&3 3>&4- 3>&- 2>&-
+```
+### Opening files for reading and writing
+```shell
+command <>file.txt 3<>file.txt
+```
+
+::: tip
+Unlick bash, you are not limited to only use file descriptors between 0 to 9. Feel free to use any valid 64-bit integer number. (learn why TODO: add this link here)
+:::
+
+## Passing shell parameters as environment to commands
+```shell
+key=value key2="value" command
+```
+
+## Pipelines
+```shell
+command | command2 | command3
+```

generator/generator.go

@@ -89,6 +89,18 @@ func (g *generator) handleExpression(expression ast.Expression) ir.Instruction {
 		return ir.String(v)
 	case ast.Var:
 		return ir.ReadVar(v)
+	case ast.QuotedString:
+		var concat ir.Concat
+		for _, expr := range v {
+			concat = append(concat, g.handleExpression(expr))
+		}
+		return concat
+	case ast.UnquotedString:
+		var concat ir.Concat
+		for _, expr := range v {
+			concat = append(concat, g.handleExpression(expr))
+		}
+		return concat
 	default:
 		panic(fmt.Sprintf("unhandled expression type (%T)", expression))
 	}

ir/ir.go

@@ -70,6 +70,19 @@ func (s String) togo() string {
 	return fmt.Sprintf("`%s`", s)
 }
 
+type Concat []Instruction
+
+func (c Concat) togo() string {
+	var str string
+	for i, ins := range c {
+		str += ins.togo()
+		if i < len(c)-1 {
+			str += "+\n"
+		}
+	}
+	return str
+}
+
 type Literal string
 
 func (s Literal) togo() string {
@@ -114,98 +127,6 @@ func (r StartCommand) togo() string {
 		`, r)
 }
 
-const (
-	FLAG_READ   = "STREAM_FLAG_READ"
-	FLAG_WRITE  = "STREAM_FLAG_WRITE"
-	FLAG_RW     = "STREAM_FLAG_RW"
-	FLAG_APPEND = "STREAM_FLAG_APPEND"
-)
-
-type OpenStream struct {
-	Name   string
-	Target Instruction
-	Mode   string
-}
-
-func (of OpenStream) togo() string {
-	return fmt.Sprintf(
-		`%s, err := runtime.OpenStream(%s, runtime.%s)
-		if err != nil {
-			shell.HandleError(err)
-			return
-		}
-		`, of.Name, of.Target.togo(), of.Mode)
-}
-
-type NewStringStream struct {
-	Target Instruction
-}
-
-func (of NewStringStream) togo() string {
-	return fmt.Sprintf("runtime.NewStringStream(%s)", of.Target.togo())
-}
-
-type CloneFDT string
-
-func (c CloneFDT) togo() string {
-	return fmt.Sprintf(
-		`%s, err := shell.CloneFDT()
-		if err != nil {
-			shell.HandleError(err)
-			return
-		}
-		defer %s.Destroy()
-		`, c, c)
-}
-
-type AddStream struct {
-	FDT        string
-	Fd         string
-	StreamName string
-}
-
-func (as AddStream) togo() string {
-	return fmt.Sprintf("%s.Add(`%s`, %s)\n", as.FDT, as.Fd, as.StreamName)
-}
-
-type GetStream struct {
-	FDT string
-	Fd  Instruction
-}
-
-func (as GetStream) togo() string {
-	return fmt.Sprintf(`%s.Get(%s)`, as.FDT, as.Fd.togo())
-}
-
-type DuplicateStream struct {
-	FDT string
-	Old string
-	New Instruction
-}
-
-func (as DuplicateStream) togo() string {
-	return fmt.Sprintf(
-		`if err := %s.Duplicate("%s", %s); err != nil {
-			shell.HandleError(err)
-			return
-		}
-	`, as.FDT, as.Old, as.New.togo())
-}
-
-type CloseStream struct {
-	FDT string
-	Fd  Instruction
-}
-
-func (c CloseStream) togo() string {
-	return fmt.Sprintf(
-		`if err := %s.Close(%s); err != nil {
-			shell.HandleError(err)
-			return
-		}
-	`, c.FDT, c.Fd.togo())
-}
-
 type Closure struct {
 	Body []Instruction
 }

ir/stream.go

@@ -0,0 +1,97 @@
+package ir
+
+import (
+	"fmt"
+)
+
+const (
+	FLAG_READ   = "STREAM_FLAG_READ"
+	FLAG_WRITE  = "STREAM_FLAG_WRITE"
+	FLAG_RW     = "STREAM_FLAG_RW"
+	FLAG_APPEND = "STREAM_FLAG_APPEND"
+)
+
+type OpenStream struct {
+	Name   string
+	Target Instruction
+	Mode   string
+}
+
+func (of OpenStream) togo() string {
+	return fmt.Sprintf(
+		`%s, err := runtime.OpenStream(%s, runtime.%s)
+		if err != nil {
+			shell.HandleError(err)
+			return
+		}
+		`, of.Name, of.Target.togo(), of.Mode)
+}
+
+type NewStringStream struct {
+	Target Instruction
+}
+
+func (of NewStringStream) togo() string {
+	return fmt.Sprintf("runtime.NewStringStream(%s)", of.Target.togo())
+}
+
+type CloneFDT string
+
+func (c CloneFDT) togo() string {
+	return fmt.Sprintf(
+		`%s, err := shell.CloneFDT()
+		if err != nil {
+			shell.HandleError(err)
+			return
+		}
+		defer %s.Destroy()
+		`, c, c)
+}
+
+type AddStream struct {
+	FDT        string
+	Fd         string
+	StreamName string
+}
+
+func (as AddStream) togo() string {
+	return fmt.Sprintf("%s.Add(`%s`, %s)\n", as.FDT, as.Fd, as.StreamName)
+}
+
+type GetStream struct {
+	FDT string
+	Fd  Instruction
+}
+
+func (as GetStream) togo() string {
+	return fmt.Sprintf(`%s.Get(%s)`, as.FDT, as.Fd.togo())
+}
+
+type DuplicateStream struct {
+	FDT string
+	Old string
+	New Instruction
+}
+
+func (as DuplicateStream) togo() string {
+	return fmt.Sprintf(
+		`if err := %s.Duplicate("%s", %s); err != nil {
+			shell.HandleError(err)
+			return
+		}
+	`, as.FDT, as.Old, as.New.togo())
+}
+
+type CloseStream struct {
+	FDT string
+	Fd  Instruction
+}
+
+func (c CloseStream) togo() string {
+	return fmt.Sprintf(
+		`if err := %s.Close(%s); err != nil {
+			shell.HandleError(err)
+			return
+		}
+	`, c.FDT, c.Fd.togo())
+}

runtime/stream.go

@@ -58,7 +58,7 @@ func NewStringStream(s string) Stream {
 type FileDescriptorTable map[string]Stream
 
 func (fdt FileDescriptorTable) Add(fd string, stream Stream) {
-	// If this stream is already open, we need to close it. otherwise, Its handler will be loats and leak.
+	// If this stream is already open, we need to close it. otherwise, Its handler will be lost and leak.
 	// This is related to pipelines in particular. when instantiating a new pipeline, we add its ends to the FDT. but if
 	// a redirection happened afterwards, it will cause the pipline handler to be lost and kept open.
 	if fdt[fd] != nil {
@@ -82,6 +82,11 @@ func (fdt FileDescriptorTable) Duplicate(newfd, oldfd string) error {
 	if stream, ok := fdt[oldfd]; !ok {
 		return fmt.Errorf("trying to duplicate bad file descriptor: %s", oldfd)
 	} else {
+		// If the new fd is already open, we need to close it. otherwise, Its handler will be lost and leak. and remain open forever.
+		if fdt[newfd] != nil {
+			_ = fdt[newfd].Close() // error here is not important.
+		}
+
 		switch stream := stream.(type) {
 		case *stringStream:
 			newbuf := &bytes.Buffer{}