github.com/SamarSidharth/kpt@v0.0.0-20231122062228-c7d747ae3ace/demos/demo-magic/README.md (about)

     1  # Demo Magic
     2  
     3  demo-magic.sh is a handy shell script that enables you to script repeatable demos in a bash environment so you don't have to type as you present. Rather than trying to type commands when presenting you simply script them and let demo-magic.sh run them for you.
     4  
     5  ## Features
     6  - Simulates typing. It looks like you are actually typing out commands
     7  - Allows you to actually run commands or pretend to do so.
     8  - Can hide commands from presentation. Useful for behind the scenes stuff that doesn't need to be shown.
     9  
    10  ## Functions
    11  
    12  ### pe
    13  Print and Execute. This function will simulate typing whatever you give it. It will then pause until you press <kbd>ENTER</kbd>. After your keypress it will run the command.
    14  
    15  ```bash
    16  #!/bin/bash
    17  
    18  pe "ls -l"
    19  ```
    20  
    21  ### p
    22  Print only. This function will simulate typing whatever you give it. It will not run the command. After typing it will pause until you press <kbd>ENTER</kbd>. After your keypress it will move on to the next instruction in your script.
    23  
    24  ```bash
    25  #!/bin/bash
    26  
    27  p "ls -l"
    28  ```
    29  
    30  ### wait
    31  Waits for the user to press <kbd>ENTER</kbd>.
    32  
    33  If `PROMPT_TIMEOUT` is defined and > 0 the demo will automatically proceed after the amount of seconds has passed.
    34  
    35  ```bash
    36  #!/bin/bash
    37  
    38  # Will wait until user presses enter
    39  PROMPT_TIMEOUT=0
    40  wait
    41  
    42  # Will wait max 5 seconds until user presses
    43  PROMPT_TIMEOUT=5
    44  wait
    45  
    46  ```
    47  
    48  ### cmd
    49  Enters script into interactive mode and allows newly typed commands to be executed within the script
    50  ```
    51  #!/bin/bash
    52  
    53  cmd
    54  ```
    55  
    56  ## Getting Started
    57  Create a shell script and include demo-magic.sh
    58  
    59  ```bash
    60  #!/bin/bash
    61  
    62  ########################
    63  # include the magic
    64  ########################
    65  . demo-magic.sh
    66  
    67  # hide the evidence
    68  clear
    69  
    70  # Put your stuff here
    71  ```
    72  
    73  Then use the handy functions to run through your demo.
    74  
    75  ## Command line usage
    76  demo-magic.sh exposes 3 options out of the box to your script.
    77  - `-d` - disable simulated typing. Useful for debugging
    78  - `-h` - prints the usage text
    79  - `-n` - set no default waiting after `p` and `pe` functions
    80  - `-w` - set no wait timeout after `p` and `pe` functions
    81  
    82  ```bash
    83  $ ./my-demo.sh -h
    84  
    85  Usage: ./my-demo.sh [options]
    86  
    87    Where options is one or more of:
    88    -h  Prints Help text
    89    -d  Debug mode. Disables simulated typing
    90    -n  No wait
    91    -w  Waits max the given amount of seconds before proceeding with demo (e.g. `-w5`)
    92  ```
    93  
    94  ## Useful Tricks
    95  
    96  ### Faking network connections
    97  Network connections during demos are often unreliable. Try and fake whatever commands would rely on a network connection. For example: Instead of trying to install node modules in a node.js application you can fake it. You can install the node_modules at home on your decent network. Then rename the directory and pretend to install it later by symlinking. If you want to be thorough you can capture the output of npm install into a log file then cat it out later to simulate the install.
    98  
    99  ```bash
   100  #!/bin/bash
   101  
   102  ########################
   103  # include the magic
   104  ########################
   105  . demo-magic.sh
   106  
   107  # hide the evidence
   108  clear
   109  
   110  # this command is typed and executed
   111  pe "cd my-app"
   112  
   113  # this command is merely typed. Not executed
   114  p "npm install"
   115  
   116  # this command runs behind the scenes
   117  ln -s cached_node_modules node_modules
   118  
   119  # cat out a log file that captures a previous successful node modules install
   120  cat node-modules-install.log
   121  
   122  # now type and run the command to start your app
   123  pe "node index.js"
   124  ```
   125  
   126  ### No waiting
   127  The -n _no wait_ option can be useful if you want to print and execute multiple commands.
   128  
   129  ```bash
   130  # include demo-magic
   131  . demo-magic.sh -n
   132  
   133  # add multiple commands
   134  pe 'git status'
   135  pe 'git log --oneline --decorate -n 20'
   136  ```
   137  
   138  However this will oblige you to define your waiting points manually e.g.
   139  ```bash
   140  ...
   141  # define waiting points
   142  pe 'git status'
   143  pe 'git log --oneline --decorate -n 20'
   144  wait
   145  pe 'git pull'
   146  pe 'git log --oneline --decorate -n 20'
   147  wait
   148  ```