jekyll_from_to_until

jekyll_from_to_until

This module provides 3 filters that return portions of a multiline string. It can be used as a Jekyll plugin, or it can be called from any Ruby program.

Matches are specified by regular expressions; the simplest regular expression is a string.

• from — returns the portion beginning with the line that satisfies a regular expression to the end of the multiline string.
• to — returns the portion from the first line to the line that satisfies a regular expression, including the matched line.
• until — returns the portion from the first line to the line that satisfies a regular expression, excluding the matched line.

Rubular is a handy online tool to try out regular expressions.

Additional Information

More information is available on the jekyll_from_to_until gem web page.

Installation

As a Jekyll Filter Plugin

If you want to use this Ruby gem in a Jekyll application, add the following line to your application's Gemfile:

group :jekyll_plugins do
  gem 'jekyll_from_to_until'
end

And then install in the usual fashion:

$ bundle

As a Dependency Of a Gem

Add the following line to your application's .gemspec:

spec.add_dependency 'jekyll_from_to_until'

And then install the dependencies in the usual fashion:

$ bundle

As a Ruby Module In a Ruby Program

Add the following line to your application's Gemfile:

gem 'jekyll_from_to_until'

And then install the dependencies in the usual fashion:

$ bundle

Jekyll Syntax

The regular expression may be enclosed in single quotes, double quotes, or nothing.

from

All of these examples perform identically.

{{ sourceOfLines | from: 'regex' }}
{{ sourceOfLines | from: "regex" }}
{{ sourceOfLines | from: regex }}

to

All of these examples perform identically.

{{ sourceOfLines | to: 'regex' }}
{{ sourceOfLines | to: "regex" }}
{{ sourceOfLines | to: regex }}

until

All of these examples perform identically.

{{ sourceOfLines | until: 'regex' }}
{{ sourceOfLines | until: "regex" }}
{{ sourceOfLines | until: regex }}

:warning: Important: the name of the filter must be followed by a colon (:). If you fail to do that an error will be generated and the Jekyll site building process will halt. The error message looks something like this: Liquid Warning: Liquid syntax error (line 285): Expected end_of_string but found string in "{{ lines | from '2' | until: '4' | xml_escape }}" in /some_directory/some_files.html Liquid Exception: Liquid error (line 285): wrong number of arguments (given 1, expected 2) in /some_directory/some_file. html Error: Liquid error (line 285): wrong number of arguments (given 1, expected 2)

Jekyll Usage

Some of the following examples use a multiline string called lines that contains 5 lines, which was created this way:

{% capture lines %}line 1
line 2
line 3
line 4
line 5
{% endcapture %}

Other examples use a multiline string called gitignore that contains the contents of a mythical .gitignore file, which looks like this:

.bsp/
project/
target/
*.gz
*.sublime*
*.swp
*.out
*.Identifier
*.log
.idea*
*.iml
*.tmp
*~
~*
.DS_Store
.idea
.jekyll-cache/
.jekyll-metadata
.sass-cache/
.yardoc/
__pycache__/
__MACOSX
_build/
_package/
_site/
bin/*.class
doc/
jekyll/doc/
node_modules/
Notepad++/
out/
package/
instances.json
rescue_ubuntu2010
rescue_ubuntu2010.b64
landingPageShortName.md
test.html
RUNNING_PID
mslinn_jekyll_plugins.zip
cloud9.tar
cloud9.zip
mslinn_aws.tar

From the third line of string

These examples return the lines of the file from the beginning of the until a line with the string "3" is found, including the matched line. The only difference between the examples is the delimiter around the regular expression.

{{ lines | from: '3' }}
{{ lines | from: "3" }}
{{ lines | from: 3 }}

The above all generate:

line 3
line 4
line 5

From Line In a File Containing 'PID'

{% capture gitignore %}{% flexible_include '.gitignore' %}{% endcapture %}
{{ gitignore | from: 'PID' | xml_escape }}

The above generates:

RUNNING_PID
mslinn_jekyll_plugins.zip
cloud9.tar
cloud9.zip
mslinn_aws.tar

To the third line of string

These examples return the lines of the file from the first line until a line with the string "3" is found, including the matched line. The only difference between the examples is the delimiter around the regular expression.

{{ lines | to: '3' }}
{{ lines | to: "3" }}
{{ lines | to: 3 }}

The above all generate:

line 1
line 2
line 3

To Line In a File Containing 'idea'

{{ gitignore | to: 'idea' }}

The above generates:

.bsp/
project/
target/
*.gz
*.sublime*
*.swp
*.out
*.Identifier
*.log
.idea*

Until the third line of string

These examples return the lines of the file until a line with the string "3" is found, excluding the matched line. The only difference between the examples is the delimiter around the regular expression.

{{ lines | until: '3' }}
{{ lines | until: "3" }}
{{ lines | until: 3 }}

The above all generate:

line 1
line 2

Until Line In a File Containing 'idea'

{{ gitignore | until: 'idea' }}

The above generates:

.bsp/
project/
target/
*.gz
*.sublime*
*.swp
*.out
*.Identifier
*.log

From the string "2" until the string "4"

These examples return the lines of the file until a line with the string "3" is found, excluding the matched line. The only difference between the examples is the delimiter around the regular expression.

{{ lines | from: '2' | until: '4' }}
{{ lines | from: "2" | until: "4" }}
{{ lines | from: 2 | until: 4 }}

The above all generate:

line 2
line 3

From Line In a File Containing 'idea' Until no match

The .gitignore file does not contain the string xx. If we attempt to match against that string the remainder of the file is returned for the to and until filter.

{{ gitignore | from: 'PID' | until: 'xx' }}

The above generates:

RUNNING_PID
mslinn_jekyll_plugins.zip
cloud9.tar
cloud9.zip
mslinn_aws.tar

More Complex Regular Expressions

The from, to and until filters can all accept regular expressions. The regular expression matches lines that have either the string sun or cloud at the beginning of the line.

{{ gitignore | from: '^(cloud|sun)' }}

The above generates:

cloud9.tar
cloud9.zip
mslinn_aws.tar

Encoding Special Characters

Special characters can be specified as HTML entities. For example, } is Open parenthesis. Belle par. A parent. 5 Resulting. OK. OK, so now what }.

{{ css | from: '.error' | to: '}' | strip }}

demo/special.html demonstrates this.

Development

After checking out the repo, run bin/setup to install dependencies.

You can also run bin/console for an interactive prompt that will allow you to experiment.

Build and Install Locally

To build and install this gem onto your local machine, run:

$ bundle exec rake install

Examine the newly built gem:

$ gem info jekyll_from_to_until

*** LOCAL GEMS ***

jekyll_from_to_until (1.0.0)
    Author: Mike Slinn
    Homepage:
    https://github.com/mslinn/jekyll_from_to_until
    License: MIT
    Installed at: /home/mslinn/.gems

    Generates Jekyll logger with colored output.

Demo Website

A test/demo website is provided in the demo directory. You can run it under a debugger, or let it run free.

The demo/_bin/debug script can set various parameters for the demo. View the help information with the -h option:

$ demo/_bin/debug -h

debug - Run the demo Jekyll website.

By default the demo Jekyll website runs without restriction under ruby-debug-ide and debase.
View it at http://localhost:4444

Options:
  -h  Show this error message

  -r  Run freely, without a debugger

Debugging the Demo

To run under a debugger, for example Visual Studio Code:

1. Set breakpoints.

2. Initiate a debug session from the command line:

   $ demo/bin/debug
   

3. Once the Fast Debugger signon appears, launch the Visual Studio Code launch configuration called Attach rdebug-ide.

4. View the generated website at http://localhost:4444.

Build and Push to RubyGems

To release a new version,

1. Update the version number in version.rb.

2. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.

3. Run the following:

   $ bundle exec rake release
   

   The above creates a git tag for the version, commits the created tag, and pushes the new .gem file to RubyGems.org.

Contributing

1. Fork the project
2. Create a descriptively named feature branch
3. Add your feature
4. Submit a pull request

License

The gem is available as open source under the terms of the MIT License.