[feat] add new lib: runtime, add docs for runtime and string (#47)

* Migrate

* local methods

* duration time

* for runtime

* ut fn

* go ver

* basic docs

* for string doc

* update docs and examples

* for err it

* for ppid and uid

* for gid

* refine lint

Author: hyorigo

config.go

@@ -8,6 +8,7 @@ import (
 	libjson "github.com/1set/starlet/lib/json"
 	librand "github.com/1set/starlet/lib/random"
 	libre "github.com/1set/starlet/lib/re"
+	librt "github.com/1set/starlet/lib/runtime"
 	libstr "github.com/1set/starlet/lib/string"
 	stdmath "go.starlark.net/lib/math"
 	stdtime "go.starlark.net/lib/time"
@@ -43,6 +44,7 @@ var allBuiltinModules = ModuleLoaderMap{
 	librand.ModuleName: librand.LoadModule,
 	libjson.ModuleName: libjson.LoadModule,
 	libstr.ModuleName:  libstr.LoadModule,
+	librt.ModuleName:   librt.LoadModule,
 }
 
 // GetAllBuiltinModuleNames returns a list of all builtin module names.

lib/runtime/README.md

@@ -0,0 +1,21 @@
+# runtime
+
+`runtime` is a Starlark module provides Go and app runtime information.
+
+## Functions
+
+### `uptime()`
+
+Returns the uptime of the current process in `time.duration`.
+
+#### Examples
+
+**basic**
+
+Returns the uptime of the current process immediately.
+
+```python
+load("runtime", "uptime")
+print(uptime())
+# Output: 883.583µs
+```

lib/runtime/runtime.go

@@ -0,0 +1,62 @@
+// Package runtime implements the Starlark module for Go and app runtime information.
+package runtime
+
+import (
+	"os"
+	grt "runtime"
+	"sync"
+	"time"
+
+	stdtime "go.starlark.net/lib/time"
+	"go.starlark.net/starlark"
+	"go.starlark.net/starlarkstruct"
+)
+
+// ModuleName defines the expected name for this Module when used in starlark's load() function, eg: load('base64', 'encode')
+const ModuleName = "runtime"
+
+var (
+	once       sync.Once
+	moduleData starlark.StringDict
+)
+
+// LoadModule loads the runtime module. It is concurrency-safe and idempotent.
+func LoadModule() (md starlark.StringDict, err error) {
+	once.Do(func() {
+		var host, pwd string
+		if host, err = os.Hostname(); err != nil {
+			return
+		}
+		if pwd, err = os.Getwd(); err != nil {
+			return
+		}
+		moduleData = starlark.StringDict{
+			ModuleName: &starlarkstruct.Module{
+				Name: ModuleName,
+				Members: starlark.StringDict{
+					"hostname":  starlark.String(host),
+					"workdir":   starlark.String(pwd),
+					"os":        starlark.String(grt.GOOS),
+					"arch":      starlark.String(grt.GOARCH),
+					"gover":     starlark.String(grt.Version()),
+					"pid":       starlark.MakeInt(os.Getpid()),
+					"ppid":      starlark.MakeInt(os.Getppid()),
+					"uid":       starlark.MakeInt(os.Getuid()),
+					"gid":       starlark.MakeInt(os.Getgid()),
+					"app_start": stdtime.Time(appStart),
+					"uptime":    starlark.NewBuiltin(ModuleName+".uptime", getUpTime),
+				},
+			},
+		}
+	})
+	return moduleData, err
+}
+
+var (
+	appStart = time.Now()
+)
+
+// getUpTime returns time elapsed since the app started.
+func getUpTime(thread *starlark.Thread, b *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+	return stdtime.Duration(time.Since(appStart)), nil
+}

lib/runtime/runtime_test.go

@@ -0,0 +1,54 @@
+package runtime_test
+
+import (
+	"testing"
+
+	itn "github.com/1set/starlet/internal"
+	rt "github.com/1set/starlet/lib/runtime"
+)
+
+func TestLoadModule_Runtime(t *testing.T) {
+	tests := []struct {
+		name    string
+		script  string
+		wantErr string
+	}{
+		{
+			name: `host`,
+			script: itn.HereDoc(`
+				load('runtime', 'hostname', 'workdir', 'os', 'arch', 'gover')
+				ss = [hostname, workdir, os, arch, gover]
+				print(ss)
+				_ = [assert.eq(type(s), "string") for s in ss]
+			`),
+		},
+		{
+			name: `process`,
+			script: itn.HereDoc(`
+				load('runtime', 'pid', 'ppid', 'uid', 'gid')
+				si = [pid, ppid, uid, gid]
+				print(si)
+				_ = [assert.eq(type(s), "int") for s in si]
+			`),
+		},
+		{
+			name: `app`,
+			script: itn.HereDoc(`
+				load('runtime', s='app_start', ut='uptime')
+				assert.eq(type(s), "time.time")
+				u = ut()
+				assert.eq(type(u), "time.duration")
+				print(s, u)
+			`),
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			res, err := itn.ExecModuleWithErrorTest(t, rt.ModuleName, rt.LoadModule, tt.script, tt.wantErr)
+			if (err != nil) != (tt.wantErr != "") {
+				t.Errorf("runtime(%q) expects error = '%v', actual error = '%v', result = %v", tt.name, tt.wantErr, err, res)
+				return
+			}
+		})
+	}
+}

lib/string/README.md

@@ -0,0 +1,153 @@
+# string
+
+`string` provides constants and functions to manipulate strings, it's intended to be a drop-in subset of Python's string module for Starlark.
+
+## Functions
+
+### `length(obj) int`
+
+Returns the length of the object; for string, it returns the number of Unicode code points, instead of bytes like `len()`.
+
+#### Parameters
+
+| name  | type     | description                                 |
+|-------|----------|---------------------------------------------|
+| `obj` | `string` | The object whose length is to be calculated |
+
+#### Examples
+
+**String**
+
+Calculate the length of a CJK string.
+
+```python
+load("string", "length")
+s = "你好"
+print(length(s), len(s))
+# Output: 2 6
+```
+
+**Misc**
+
+Calculate the length of a list, set and map.
+
+```python
+load("string", "length")
+print(length([1, 2, 3]), length(set([1, 2])), length({1: 2}))
+# Output: 3 2 1
+```
+
+### `reverse(str) string`
+
+Returns the reversed string of the given value.
+
+#### Parameters
+
+| name  | type     | description                     |
+|-------|----------|---------------------------------|
+| `str` | `string` | A string that is to be reversed |
+
+#### Examples
+
+**String**
+
+Reverse a string.
+
+```python
+load("string", "reverse")
+s = "123我爱你"
+print(reverse(s))
+# Output: 你爱我321
+```
+
+### `escape(str) string`
+
+Converts the characters "&", "<", ">", '"' and "'" in string to their corresponding HTML entities.
+
+#### Parameters
+
+| name  | type     | description                          |
+|-------|----------|--------------------------------------|
+| `str` | `string` | A string which is to be HTML escaped |
+
+#### Examples
+
+**String**
+
+Escape a string.
+
+```python
+load("string", "escape")
+s = "Hello<World>"
+print(escape(s))
+# Output: Hello&lt;World&gt;
+```
+
+### `unescape(str) string`
+
+Converts the HTML entities in a string back to their corresponding characters.
+
+#### Parameters
+
+| name  | type     | description           |
+|-------|----------|-----------------------|
+| `str` | `string` | A HTML escaped string |
+
+#### Examples
+
+**String**
+
+Unescape a string.
+
+```python
+load("string", "unescape")
+s = "You&amp;Me"
+print(unescape(s))
+# Output: "You&Me"
+```
+
+### `quote(str) string`
+
+Returns a shell-escaped version of the string str. This returns a string that can safely be used as one token in a shell command line.
+
+#### Parameters
+
+| name  | type     | description                    |
+|-------|----------|--------------------------------|
+| `str` | `string` | A string which is to be quoted |
+
+#### Examples
+
+**String**
+
+Quote a string.
+
+```python
+load("string", "quote")
+s = "Hello World"
+print(quote(s))
+# Output: "Hello World"
+```
+
+### `unquote(str) string`
+
+Returns a shell-unescaped version of the string str. This returns a string that was used as one token in a shell command line.
+
+#### Parameters
+
+| name  | type     | description                      |
+|-------|----------|----------------------------------|
+| `str` | `string` | A string which is to be unquoted |
+
+#### Examples
+
+**String**
+
+Unquote a string.
+
+```python
+load("string", "unquote")
+s = '"Hello\tWorld"'
+print(unquote(s))
+World
+```

lib/string/string_test.go

@@ -217,7 +217,7 @@ func TestLoadModule_String(t *testing.T) {
 		t.Run(tt.name, func(t *testing.T) {
 			res, err := itn.ExecModuleWithErrorTest(t, ls.ModuleName, ls.LoadModule, tt.script, tt.wantErr)
 			if (err != nil) != (tt.wantErr != "") {
-				t.Errorf("hash(%q) expects error = '%v', actual error = '%v', result = %v", tt.name, tt.wantErr, err, res)
+				t.Errorf("string(%q) expects error = '%v', actual error = '%v', result = %v", tt.name, tt.wantErr, err, res)
 				return
 			}
 		})

module_test.go

@@ -13,7 +13,7 @@ import (
 )
 
 var (
-	builtinModules = []string{"base64", "go_idiomatic", "hashlib", "http", "json", "math", "random", "re", "string", "struct", "time"}
+	builtinModules = []string{"base64", "go_idiomatic", "hashlib", "http", "json", "math", "random", "re", "runtime", "string", "struct", "time"}
 )
 
 func TestListBuiltinModules(t *testing.T) {