README.md features

README.md

@@ -1,28 +1,58 @@
-##  punkshell - an alternative Tcl Shell
+##  punkshell - an alternative Tcl Shell
-
+
-BSD license
+BSD license
-
+
-2023-08  Note: this is **alpha** level software and still highly experimental.
+2023-08  Note: this is **alpha** level software and still highly experimental.
-
+
-
+
-### Features
+### Features
-- default ansi color output - toggle with 'colour on' and 'colour off'
+- default ansi color output - toggle with 'colour on' and 'colour off'
-- experimental functional language features. (will not be performant until more work is done on script compilation)
+- experimental functional/pattern-matching language features. (will not be performant until more work is done on script compilation)
-    e.g  
+    e.g.1 basic pipeline with 2 segments  
-    `var_pipe_output.=  var_list.= list a b c |> string toupper`
+    `var_pipe_output.=  var_list.= list a b c |> string toupper`
-- easy execution of externals commands with return of stdout, stderr and the exitcode of the process
+    e.g.2 basic pattern-match multi-assignment to variables x y & z
-   - `run <comand> ...`
+    `x@0,y@1,z@2.= list a b c`  equivalently: `x@,y@,z@.= list a b c`  or even `x@,y@,z@= {a b c}`  
-       (return exitcode of process - and allows process writes to stderr/stdout to appear in console as they occur)
+    `x/0,y/1,z/2,zz/3.= list a b c` is similar - but the use of forward-slash instead of @ will not produce a mismatch if an index is out of range.
-   - `runout <command> ...` 
+     where .= indicates following arguments form a command, and a plain = accepts only a single argument as a value
-       (return stdout of process - no output until completion) 
+     The diminutive case of this is `x= "something"`  as equivalent to `set x "something"` 
-   - `runerr <command> ...`
+     Assignment operations and pattern-matches are slightly optimised to bytecompile, but are unlikely to compete with raw Tcl commands performance-wise.
-       (return stderr of process - no output until completion)
+    e.g.3 destructuring pattern-match. Get value of key 'k1' from last item in a list of dicts. 
-   - `runx  <command> ...`
+    `x@end/@@k1.= list {k1 aaa} {k1 bb}`  returns bbb 
-       (return a dict of stdout stderr exitcode - no output until completion)
+    
-
+    There are many more pattern-matching features yet to be documented.
-
+- easy execution of externals commands with return of stdout, stderr and the exitcode of the process
-
+    - `run <comand> ...`
-#### very unripe parts:
+       (return exitcode of process - and allows process writes to stderr/stdout to appear in console as they occur)
-- commandline options - in need of urgent work to document and lock down specifics - in particular: punkshell somescript.tcl needs a fix to emit errors.
+    - `runout <command> ...` 
-- shellfilter - api is clumsy
+       (return stdout of process - no output until completion) 
-- scriptlib - will likely be reorganised/pruned significantly
+    - `runerr <command> ...`
+       (return stderr of process - no output until completion)
+    - `runx  <command> ...`
+       (return a dict of stdout stderr exitcode - no output until completion)
+- namespace browser (contextual - allowing running of commands within the active namespace - analogous to 'cd' for directories)
+    -  `n/`  - display child namespaces of current namespace  (alias `:/`)
+         also `n/ <globpattern>` to restrict output
+    -  `n/ <childns>`  - if the argument doesn't contain glob chars '*' or '?' - attempt to switch to a child namespace of that name. Analogous to `cd <dir>`
+         list any sub namespaces of the namespace we just switched to.
+    -  `n//` - display child namespaces and commands  (alias `://`)
+        with colourised indication of type such as proc,alias,ensemble,imported,exported where possible. 
+        (renamed aliases and builtins and commands loaded from binaries will appear unmarked)
+    -  `nn/` - move up one namespace towards root namespace '::'  analogous to `cd ..`   (alias `::/`)
+    -  `n/new <somename>` - create a child namespace called 'somename' and switch to it in one operation.  (alias `:/new`)
+- cross-platform alternative to cd & ls/dir without invoking child processes. Display colourised listing of dirs and folders - with vfs indication.
+    -  `d/` - list current directory (alias `./`)
+        also `d/ <globpattern>` to restrict output
+    -  `d/ <subdir>` - switch to subdir and list contents in one operation 
+    -  `dd/` - move up one directory and output listing. Roughly equivalent to `cd ..` followed by dir or ls  (alias `../`)
+    -  `d/new <folder>` - create a child directory and switch to it in one operation. (alias `./new <folder>`)
+
+#### missing
+- raw mode REPL (read-eval-print-loop) to allow commandline completion etc. Initial version is linemode. (intention is to allow different REPLs to be plugged)
+- documentation!
+- tests
+
+
+#### very unripe parts:
+- commandline options - in need of urgent work to document and lock down specifics - in particular: punkshell somescript.tcl needs a fix to emit errors.
+- shellfilter - api is clumsy
+- scriptlib - will likely be reorganised/pruned significantly