os: document os.ls (using readdir), add example (#20622)

Author: scriptmaster

doc/docs.md

@@ -7295,14 +7295,29 @@ Make sure that in command you use a path to a V's file,
 in that case you need to modify content of a folder (add new file, for example),
 because changes in *message.v* will have no effect.
 
-Functions that you want to be reloaded must have `[live]` attribute
+Functions that you want to be reloaded must have `@[live]` attribute
 before their definition.
 
 Right now it's not possible to modify types while the program is running.
 
 More examples, including a graphical application:
 [github.com/vlang/v/tree/master/examples/hot_reload](https://github.com/vlang/v/tree/master/examples/hot_reload).
 
+#### About keeping states in hot reloading functions with v -live run
+V's hot code reloading relies on marking the functions that you want to reload with `@[live]`,
+then compiling a shared library of these `@[live]` functions, and then
+your v program loads that shared library at runtime.
+
+V (with the -live option) starts a new thread, that monitors the source files for changes,
+and when it detects modifications, it recompiles the shared library, and reloads it at runtime,
+so that new calls to those @[live] functions will be made to the newly loaded library.
+
+It keeps all the accumulated state (from locals outside the @[live] functions,
+from heap variables and from globals), allowing to tweak the code in the merged functions quickly.
+
+When there are more substantial changes (to data structures, or to functions that were not marked),
+you will have to restart the running app manually.
+
 ### Cross-platform shell scripts in V
 
 V can be used as an alternative to Bash to write deployment scripts, build scripts, etc.

examples/readdir.v

@@ -0,0 +1,14 @@
+import os
+
+// Example usage of os.ls (in the form of top-level statements)
+println('readdir example using os.ls')
+
+entries := os.ls(os.home_dir()) or { [] }
+
+for entry in entries {
+	if os.is_dir(os.join_path(os.home_dir(), entry)) {
+		println('dir: ${entry}')
+	} else {
+		println('file: ${entry}')
+	}
+}

vlib/os/os.v

@@ -608,6 +608,7 @@ pub fn join_path_single(base string, elem string) string {
 }
 
 // walk_ext returns a recursive list of all files in `path` ending with `ext`.
+// For listing only one level deep, see: `os.ls`
 pub fn walk_ext(path string, ext string) []string {
 	mut res := []string{}
 	impl_walk_ext(path, ext, mut res)
@@ -637,6 +638,7 @@ fn impl_walk_ext(path string, ext string, mut out []string) {
 // When a file is encountered, it will call the callback `f` with current file as argument.
 // Note: walk can be called even for deeply nested folders,
 // since it does not recurse, but processes them iteratively.
+// For listing only one level deep, see: `os.ls`
 pub fn walk(path string, f fn (string)) {
 	if path.len == 0 {
 		return
@@ -674,6 +676,7 @@ pub type FnWalkContextCB = fn (voidptr, string)
 // and the path to the file in its second parameter.
 // Note: walk_with_context can be called even for deeply nested folders,
 // since it does not recurse, but processes them iteratively.
+// For listing only one level deep, see: `os.ls`
 pub fn walk_with_context(path string, context voidptr, fcb FnWalkContextCB) {
 	if path.len == 0 {
 		return

vlib/os/os_nix.c.v

@@ -282,6 +282,19 @@ fn init_os_args(argc int, argv &&u8) []string {
 	return args_
 }
 
+// ls returns ![]string of the files and dirs in the given `path` ( os.ls uses C.readdir ). Symbolic links are returned to be files. For recursive list see os.walk functions.
+// See also: `os.walk`, `os.walk_ext`, `os.is_dir`, `os.is_file`
+// Example: https://github.com/vlang/v/blob/master/examples/readdir.v
+// ```
+//   entries := os.ls(os.home_dir()) or { [] }
+//   for entry in entries {
+//     if os.is_dir(os.join_path(os.home_dir(), entry)) {
+//       println('dir: $entry')
+//     } else {
+//       println('file: $entry')
+//     }
+//   }
+// ```
 pub fn ls(path string) ![]string {
 	if path.len == 0 {
 		return error('ls() expects a folder, not an empty string')