diff --git a/examples/a_basic_example.rb b/examples/a_basic_example.rb
new file mode 100755
index 0000000..7db696c
--- /dev/null
+++ b/examples/a_basic_example.rb
@@ -0,0 +1,10 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  opt :monkey, "Use monkey mode"                    # flag --monkey, default false
+  opt :name, "Monkey name", :type => :string        # string --name <s>, default nil
+  opt :num_limbs, "Number of limbs", :default => 4  # integer --num-limbs <i>, default to 4
+end
+p opts
+
diff --git a/examples/banners1.rb b/examples/banners1.rb
new file mode 100755
index 0000000..7a319b6
--- /dev/null
+++ b/examples/banners1.rb
@@ -0,0 +1,11 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+Optimist::options do
+  synopsis "Overall synopsis of this program"
+  version "cool-script v0.3 (code-name: apple-cake)"
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+end
diff --git a/examples/banners2.rb b/examples/banners2.rb
new file mode 100755
index 0000000..f413a26
--- /dev/null
+++ b/examples/banners2.rb
@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+Optimist::options do
+  synopsis "Overall synopsis of this program"
+  version "cool-script v0.3.1 (code-name: apple-cake)"
+  banner "My Banner"
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+end
diff --git a/examples/banners3.rb b/examples/banners3.rb
new file mode 100755
index 0000000..fe548d5
--- /dev/null
+++ b/examples/banners3.rb
@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+Optimist::options do
+  version "cool-script v0.3.2 (code-name: apple-cake)"
+  banner self.version  ## print out the version in the banner
+  banner "drinks"
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  banner "drink control"    ## can be used for categories
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+  banner "other controls"
+end
diff --git a/examples/medium_example.rb b/examples/medium_example.rb
new file mode 100755
index 0000000..75f4230
--- /dev/null
+++ b/examples/medium_example.rb
@@ -0,0 +1,15 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  version "cool-script v0.1 (code-name: bananas foster)"
+  banner "This script is pretty cool."
+  opt :juice, "use juice"
+  opt :milk, "use milk"
+  opt :litres, "quantity of liquid", :default => 2.0
+  opt :brand, "brand name of the liquid", :type => :string
+  opt :config, "config file path", :type => String, :required => true
+  opt :drinkers, "number of people drinking the liquid", :default => 6
+end
+Optimist::die :drinkers, "must be value a greater than zero" if opts[:drinkers] < 1
+Optimist::die :config, "must point to an existing file" unless File.exist?(opts[:config]) if opts[:config]
diff --git a/examples/partialmatch.rb b/examples/partialmatch.rb
new file mode 100755
index 0000000..bc5325f
--- /dev/null
+++ b/examples/partialmatch.rb
@@ -0,0 +1,18 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options(ARGV, exact_match: false) do
+  opt :apple, "An apple"
+  opt :apple_sauce, "Cooked apple puree"
+  opt :atom, "Smallest unit of ordinary matter"
+  opt :anvil, "Heavy metal"
+  opt :anteater, "Eats ants"
+end
+p opts
+
+# $ ./partialmatch.rb  --anv 1
+# {:apple=>false, :apple_sauce=>false, :atom=>false, :anvil=>true, :anteater=>false, :help=>false, :anvil_given=>true}
+#
+# $ ./partialmatch.rb  --an 1
+# Error: ambiguous option '--an' matched keys (anvil,anteater).
+# Try --help for help.
diff --git a/examples/permitted.rb b/examples/permitted.rb
new file mode 100755
index 0000000..8e57a21
--- /dev/null
+++ b/examples/permitted.rb
@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+opts = Optimist::options do
+  opt :french, "starts with french", type: String,
+      permitted: %w(fries toast),
+      permitted_response: "option %{arg} must be something that starts " +
+      "with french, e.g. %{permitted} but you gave '%{given}'"
+  opt :dog, "starts with dog", permitted: %r/(house|bone|tail)/, type: String
+  opt :zipcode, "zipcode", permitted: %r/^[0-9]{5}$/, default: '39759',
+      permitted_response: "option %{arg} must be a zipcode, a five-digit number from 00000..99999"
+  opt :adult, "adult age", permitted: (18...99), type: Integer
+  opt :minor, "minor age", permitted: (0..18), type: Integer
+  opt :letter, "a letter", permitted: ('a'...'z'), type: String
+end
+
+p opts
+
+# $ ./permitted.rb -z 384949
+# Error: option -z must be a zipcode, a five-digit number from 00000..99999.
+# Try --help for help.
+#
+# $ ./permitted.rb --minor 19
+# Error: option '--minor' only accepts value in range of: 0..18.
+# Try --help for help.
+#
+# $ ./permitted.rb -f frog
+# Error: option -f must be something that starts with french, e.g. ["fries", "toast"] but you gave 'frog'.
+# Try --help for help.
diff --git a/examples/types_custom.rb b/examples/types_custom.rb
new file mode 100755
index 0000000..fd9c103
--- /dev/null
+++ b/examples/types_custom.rb
@@ -0,0 +1,43 @@
+#!/usr/bin/env ruby
+require_relative '../lib/optimist'
+
+class ZipCode
+  REGEXP = %r/^(?<zip>[0-9]{5})(\-(?<plusfour>[0-9]{4}))?$/
+  def initialize(zipstring)
+    matcher = REGEXP.match(zipstring)
+    raise "Invalid zip-code" unless matcher
+    @zip = matcher[:zip]
+    @plusfour = matcher[:plusfour]
+  end
+end
+
+#module Optimist
+class ZipCodeOption < Optimist::Option
+  # register_alias registers with the global parser.
+  register_alias :zipcode
+  def type_format ; "=<zip>" ; end # optional for use with help-message
+  def parse(paramlist, _neg_given)
+    paramlist.map do |plist|
+      plist.map do |param_string|
+        raise Optimist::CommandlineError, "option '#{self.name}' should be formatted as a zipcode" unless param_string=~ ZipCode::REGEXP
+        ZipCode.new(param_string)
+      end
+    end
+  end
+end
+
+opts = Optimist::options do
+  opt :zipcode, "United states postal code", :type => :zipcode 
+end
+
+p opts[:zipcode]
+
+# $ ./types_custom.rb --zipcode 39759
+# <ZipCode:0x0000000000a34968 @zip="39759", @plusfour=nil>
+#
+# $ ./types_custom.rb --zipcode 39759-0001
+# <ZipCode:0x000000000117a100 @zip="39759", @plusfour="0001">
+#
+# $ ./types_custom.rb --zipcode 384134
+# Error: option 'zipcode' should be formatted as a zipcode.
+# Try --help for help.