Add docs for advanced value source

Author: dearchap

docs/v3/examples/flags/value-sources.md

@@ -136,78 +136,85 @@ Note that default values are set in the same order as they are defined in the
 
 #### Values from alternate input sources (YAML, TOML, and others)
 
-There is a separate package altsrc that adds support for getting flag values
+There is a separate package [altsrc](https://github.com/urfave/cli-altsrc) that adds support for getting flag values
 from other file input sources.
 
-Currently supported input source formats:
+Currently supported input source formats by that library are:
 
 - YAML
 - JSON
 - TOML
 
-In order to get values for a flag from an alternate input source the following
-code would be added to wrap an existing cli.Flag like below:
+A simple straight forward usage would be
 
 ```go
-  // --- >8 ---
-  altsrc.NewIntFlag(&cli.IntFlag{Name: "test"})
-```
+package main
 
-Initialization must also occur for these flags. Below is an example initializing
-getting data from a yaml file below.
+import (
+	"log"
+	"os"
+	"context"
 
-```go
-  // --- >8 ---
-  command.Before = func(ctx context.Context, cmd *Command) (context.Context, error) {
-	return ctx, altsrc.InitInputSourceWithContext(command.Flags, NewYamlSourceFromFlagFunc("load"))
-  }
-```
+	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli-altsrc/v3"
+)
 
-The code above will use the "load" string as a flag name to get the file name of
-a yaml file from the cli.Context.  It will then use that file name to initialize
-the yaml input source for any flags that are defined on that command.  As a note
-the "load" flag used would also have to be defined on the command flags in order
-for this code snippet to work.
+func main() {
+	cmd := &cli.Command{
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:     "password",
+				Aliases:  []string{"p"},
+				Usage:    "password for the mysql database",
+				Sources: altsrc.YAML("somekey", altsrc.StringSourcer("/path/to/filename")),
+			},
+		},
+	}
 
-Currently only YAML, JSON, and TOML files are supported but developers can add
-support for other input sources by implementing the altsrc.InputSourceContext
-for their given sources.
+	if err := cmd.Run(context.Background(), os.Args); err != nil {
+		log.Fatal(err)
+	}
+}
+```
 
-Here is a more complete sample of a command using YAML support:
+Sometime the source name is itself provided by another CLI flag. To allow the library to "lazy-load"
+the file when needed we use the `altsrc.NewStringPtrSourcer` function to bind the value of the flag 
+to a pointer that is set as a destination of another flag
 
-<!-- {
-  "args": ["&#45;&#45;help"],
-  "output": "&#45&#45;test int.*default: 0"
-} -->
 ```go
 package main
 
 import (
-	"context"
-	"fmt"
+	"log"
 	"os"
+	"context"
 
-	altsrc "github.com/urfave/cli-altsrc/v3"
 	"github.com/urfave/cli/v3"
+	"github.com/urfave/cli-altsrc/v3"
 )
 
 func main() {
-	flags := []cli.Flag{
-		&cli.IntFlag{
-			Name:    "test",
-			Sources: altsrc.YAML("key", "/path/to/file"),
-		},
-		&cli.StringFlag{Name: "load"},
-	}
-
+	var filename string
 	cmd := &cli.Command{
-		Action: func(context.Context, *cli.Command) error {
-			fmt.Println("--test value.*default: 0")
-			return nil
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:     "file",
+				Aliases:  []string{"f"},
+				Value:  "/path/to/default",
+				Usage:    "filename for mysql database",
+				Destination: &filename,
+			},
+			&cli.StringFlag{
+				Name:     "password",
+				Aliases:  []string{"p"},
+				Usage:    "password for the mysql database",
+				Sources: altsrc.YAML("somekey", altsrc.NewStringPtrSourcer(&filename)),
+			},
 		},
-		Flags: flags,
 	}
 
-	cmd.Run(context.Background(), os.Args)
+	if err := cmd.Run(context.Background(), os.Args); err != nil {
+		log.Fatal(err)
+	}
 }
-```
+```