Improve examples (#82)

improve examples

Author: DannyBen

README.md

@@ -15,6 +15,7 @@ Create beautiful bash scripts from simple YAML configuration
 
 </div>
 
+
 ## Table of Contents
 
 - [Table of Contents](#table-of-contents)
@@ -37,6 +38,7 @@ Create beautiful bash scripts from simple YAML configuration
 
 ---
 
+
 ## Installation
 
 ```shell
@@ -84,8 +86,17 @@ Bahsly is responsible for:
   - **YAML parsing**.
   - and more.
 
+
 ## Usage
 
+The `bashly.yml` file can be set up to generate two types of scripts:
+
+1. Script with commands (for example, like `docker` or `git`).
+2. Script without commands (for example, like `ls`)
+
+This is detected automatically by the contents of the configuration: If it
+contains a `commands` definition, it will generate a script with commands.
+
 In an empty directory, create a sample configuration file by running
 
 ```shell
@@ -153,32 +164,11 @@ $ ./download a --force
 downloading a with --force
 ```
 
-## Examples
-
-The `bashly.yml` file can be set up to generate two types of scripts:
-
-1. Script with commands (for example, like `docker` or `git`).
-2. Script without commands (for example, like `ls`)
-
-This is detected automatically by the contents of the configuration: If it
-contains a `commands` definition, it will generate a script with commands.
-
 
-### Sample configuration for a script without commands
-
-- Generate this script by running `bashly generate --minimal`
-- [See the initial sample bashly.yml file](examples/minimal/src/bashly.yml)
-- [See the generated bash script](examples/minimal/download)
-
-### Sample configuration for a script with commands
-
-- Generate this script by running `bashly generate`
-- [See the initial sample bashly.yml file](examples/commands/src/bashly.yml)
-- [See the generated bash script](examples/commands/cli)
-
-
-See the [examples](examples) folder for more examples.
+## Examples
 
+The [examples folder](examples#readme) contains many detailed and documented 
+example configuration files, with their output.
 
 
 ## Configuration Reference
@@ -249,7 +239,7 @@ The `-v` and `-h` flags will be used as the short options for `--version` and
 `--help` respectively **only if you are not using them in any of your own
 flags**.
 
-### Environment Variable options
+### Environment variable options
 
 If an environment variable is defined as required (false by default), the
 execution of the script will be halted with a friendly error if it is not
@@ -337,7 +327,6 @@ The generated script will execute `git status`.
 See the [extensible-delegate example](examples/extensible-delegate).
 
 
-
 ## Real World Examples
 
 - [Rush][rush] - a Personal Package Manager

Runfile

@@ -16,7 +16,7 @@ end
 
 help   "Run shellcheck on all examples"
 action :shellcheck do
-  examples.each do |example|
+  Example.executables.each do |example|
     success = system "shellcheck #{example}"
     color = success ? 'txtgrn' : 'txtred'
     say "- shellcheck !#{color}!#{example}"
@@ -31,34 +31,100 @@ action :changelog do
   run "cat .changelog.old.md >> CHANGELOG.md"
 end
 
-def examples
-  [
-    "examples/catch_all/download",
-    "examples/catch_all_advanced/cli",
-    "examples/colors/colorly",
-    "examples/command-default/ftp",
-    "examples/command-groups/ftp",
-    "examples/commands-nested/cli",
-    "examples/commands/cli",
-    "examples/config-ini/configly",
-    "examples/custom-includes/download",
-    "examples/custom-strings/download",
-    "examples/default-values/convert",
-    "examples/dependencies/cli",
-    "examples/docker-like/docker",
-    "examples/environment-variables/cli",
-    "examples/extensible-delegate/mygit",
-    "examples/extensible/cli",
-    "examples/git-like/git",
-    "examples/minimal/download",
-    "examples/minus-v/cli",
-    "examples/multiline/multi",
-    "examples/whitelist/login",
-    "examples/yaml/yaml",
-    "spec/fixtures/workspaces/catch-all-no-args/download",
-    "spec/fixtures/workspaces/flag-args-with-dash/argflag",
-    "spec/fixtures/workspaces/short-command-code/rush",
-  ]
+help   "Append the content of bashly.yml to all example READMEs"
+action :examples do
+  Example.all.each do |example|
+    say example.dir
+    example.regenerate_readme
+  end
+end
+
+class Example
+  class << self
+    def dirs
+      @dirs ||= Dir['examples/*'].select { |f| File.directory? f }
+    end
+
+    def all
+      dirs.map { |dir| Example.new dir }
+    end
+
+    def executables
+      all.map &:executable
+    end
+  end
+
+  attr_reader :dir
+
+  def initialize(dir)
+    @dir = dir
+  end
+
+  def config
+    @config ||= YAML.load_file(yaml_path)
+  end
+
+  def yaml
+    @yaml ||= File.read(yaml_path).strip
+  end
+
+  def yaml_path
+    "#{dir}/src/bashly.yml"
+  end
+
+  def readme_path
+    "#{dir}/README.md"
+  end
+
+  def readme
+    File.read readme_path
+  end
+
+  def test_commands
+    File.read("#{dir}/test.sh").scan(/\.\/#{config['name']}.*/)
+  end
+
+  def test_output
+    result = "```shell\n"
+    test_commands.each do |command|
+      result += "$ #{command}\n\n"
+      Dir.chdir dir do
+        result += `#{command} 2>&1`
+        result += "\n\n"
+      end
+    end
+    result += "```\n\n"
+    result
+  end
+
+  def regenerate_readme
+    File.write readme_path, generated_readme
+  end
+
+  def generated_readme
+    marker = '-----'
+    content = readme.split(marker)[0].strip
+    <<~EOF
+    #{content}
+
+    #{marker}
+
+    ## `bashly.yml`
+
+    ```yaml
+    #{yaml}
+    ```
+
+    ## Generated script output
+
+    #{test_output}
+
+    EOF
+  end
+
+  def executable
+    "#{dir}/#{config['name']}"
+  end
 end
 
 require './debug.rb' if File.exist? 'debug.rb'

examples/README.md

@@ -0,0 +1,43 @@
+# Bashly Examples
+
+Each of these examples demonstrates one aspect or feature of bashly.
+
+## Basic use
+
+- [minimal](minimal#readme) - the most basic "hello world" example
+- [commands](commands#readme) - a script with sub-commands
+- [commands-nested](commands-nested#readme) - a script with nested sub-commands
+
+## Basic features
+
+- [command-default](command-default#readme) - configuring a default command
+- [dependencies](dependencies#readme) - halting script execution unless certain dependencies are installed
+- [environment-variables](environment-variables#readme) - halting script execution unless certain environment variables are set
+- [default-values](default-values#readme) - arguments and flags with default values
+- [minus-v](minus-v#readme) - using `-v` and `-h` in your script
+- [multiline](multiline#readme) - help messages with multiple lines
+
+## Advanced configuration features
+
+- [catch-all](catch-all#readme) - a command that can receive an arbitrary number of arguments
+- [catch-all-advanced](catch-all-advanced#readme) - another example for the `catch_all` option
+- [extensible](extensible#readme) - letting your script's users extend the script
+- [extensible-delegate](extensible-delegate#readme) - extending your script by delegating commands to an external executable
+- [whitelist](whitelist#readme) - arguments and flags with a predefined allowed list of values
+
+## Customization
+
+- [command-groups](command-groups#readme) - grouping sub-commands in logical sections
+- [custom-strings](custom-strings#readme) - configuring the script's error and usage texts
+- [custom-includes](custom-includes#readme) - adding and organizing your custom functions
+
+## Real-world-like examples
+
+- [docker-like](docker-like#readme) - a sample script with deep commands (like `docker container run`)
+- [git-like](git-like#readme) - a sample script with sub-commands similar to git
+
+## Bashly library features
+
+- [config-ini](config-ini#readme) - using the config (INI) functions
+- [colors](colors#readme) - using the color print feature
+- [yaml](yaml#readme) - using the YAML reading functions