Merge pull request #4223 from jekyll/pull/sample-filter

Merge pull request 4223

.travis.yml

@@ -19,6 +19,9 @@ env:
   matrix:
     - TEST_SUITE=test
     - TEST_SUITE=cucumber
+branches:
+  only:
+    - master
 before_script: bundle update
 script: script/cibuild
 notifications:

lib/jekyll/filters.rb

@@ -281,6 +281,16 @@ module Jekyll
       new_ary
     end
 
+    def sample(input, num = 1)
+      return input unless input.respond_to?(:sample)
+      n = num.to_i rescue 1
+      if n == 1
+        input.sample
+      else
+        input.sample(n)
+      end
+    end
+
     # Convert an object into its String representation for debugging
     #
     # input - The Object to be converted

site/_docs/templates.md

@@ -246,6 +246,20 @@ common tasks easier.
         </p>
       </td>
     </tr>
+    <tr>
+      <td>
+        <p class="name"><strong>Sample</strong></p>
+        <p>Pick a random value from an array. Optional: pick multiple values.</p>
+      </td>
+      <td class="align-center">
+        <p>
+         <code class="filter">{% raw %}{{ site.pages | sample }}{% endraw %}</code>
+        </p>
+        <p>
+         <code class="filter">{% raw %}{{ site.pages | sample:2 }}{% endraw %}</code>
+        </p>
+      </td>
+    </tr>
   </tbody>
 </table>
 </div>

test/test_filters.rb

@@ -388,5 +388,19 @@ class TestFilters < JekyllUnitTest
       end
     end
 
+    context "sample filter" do
+      should "return a random item from the array" do
+        input = %w(hey there bernie)
+        assert_includes input, @filter.sample(input)
+      end
+
+      should "allow sampling of multiple values (n > 1)" do
+        input = %w(hey there bernie)
+        @filter.sample(input, 2).each do |val|
+          assert_includes input, val
+        end
+      end
+    end
+
   end
 end