mainmatter / highlight Goto Github PK

Syntax Higlighting plugin for Ruby on Rails

License: MIT License

Ruby 82.68% CSS 17.32%

highlight's Introduction

Highlight

Highlight is a simple syntax highlighting gem for Ruby and Rails. It's basically a wrapper around the popular http://pygments.org highlighter that's written in Python and supports an impressive number of languages.

If pygments is installed on the machine and in the PATH, that binary is used, otherwise the plugin falls back to the web API at http://pygments.simplabs.com/, created by Trevor Turk.

See the API docs at http://rdoc.info/projects/simplabs/highlight.

Usage

Highlight can either be used standalone via

require 'simplabs/highlight'
Simplabs::Highlight.highlight(:ruby, 'class Test; end')

or in Rails where it adds the highlight_code helper:

highlight_code(language, code = nil, &block)

language may be either a Symbol or a String (see supported languages below). The code can be passed either as a string or inside a block, e.g.:

highlight_code(:ruby, 'class Test; end')

highlight_code(:ruby) do
  klass = 'class'
  name  = 'Test'
  _end  = 'end'
  "#{klass} #{name}; #{_end}"
end

Since highlighting the code takes a while, all highlighted source code should be cached, e.g.:

<%- code = 'class Test; end' -%>
<%- cache Digest::SHA1.hexdigest(code) do -%>
  <%= highlight_code(:ruby, code) -%>
<%- end -%>

Supported Languages

The following languages are supported (there are probably more that are supported by pygments). All of the paranthesized identifiers may be used as parameters for highlight to denote the language the source code to highlight is written in (use either Symbols or Strings).

Actionscript (as, as3, actionscript)
Applescript (applescript)
bash (bash, sh)
C (c, h)
Clojure (clojure)
C++ (c++, cpp, hpp)
C# (c#, csharp, cs)
CSS (css)
diff (diff)
Dylan (dylan)
Erlang (erlang, erl, er)
HTML (html, htm)
Java (java)
JavaScript (javascript, js, jscript)
JSP (jsp)
Make (make, basemake, makefile)
Objective-C (objective-c)
OCaml (ocaml)
Perl (perl, pl)
PHP (php)
Python (python, py)
RHTML (erb, rhtml)
Ruby (ruby, rb)
Scala (scala)
Scheme (scheme)
Smalltalk (smalltalk)
Smarty (smarty)
SQL (sql)
XML (xml, xsd)
XSLT (xslt)
YAML (yaml, yml)

Installation

Installation is as easy as

gem install highlight

To use highlight in Rails apps, you have to define the dependency in the Gemfile:

gem 'highlight', :require => 'simplabs/highlight'

Highlight also comes with a default CSS file that defines styles for the highlighted code. This CSS file can be copied to your application's public/stylesheets directory via

./bin/rails generate highlight_styles

If you don't have python and pygments installed, you will need that too. For instructions on installing pygments, refer to http://pygments.org/docs/installation/.

Author

Acknowledgements

The actual highlighting is done by Pygments (http://pygments.org).

highlight's People

Contributors

Stargazers

Watchers

highlight's Issues

pygments.appspot.com shutting down

pygments.appspot.com is shutting down soon, please find an alternative source for syntax highlighting

Generator highlight_styles cannot be found

$ gem install highlight
Successfully installed highlight-1.1.2
1 gem installed
Installing ri documentation for highlight-1.1.2...
Installing RDoc documentation for highlight-1.1.2...

$ rails generate highlight_styles
Could not find generator highlight_styles.

I tried this in a Rails 3.0.5 app and installed highlight also via bundler.

optionally use the pygments web api

I made this so I can use pygments on heroku etc:

http://pygments.appspot.com/

...might be nice to support...?

Also, the link to the github issues is pointing to the old url.

License missing from gemspec

RubyGems.org doesn't report a license for your gem. This is because it is not specified in the gemspec of your last release.

via e.g.

spec.license = 'MIT'
# or
spec.licenses = ['MIT', 'GPL-2']

Including a license in your gemspec is an easy way for rubygems.org and other tools to check how your gem is licensed. As you can image, scanning your repository for a LICENSE file or parsing the README, and then attempting to identify the license or licenses is much more difficult and more error prone. So, even for projects that already specify a license, including a license in your gemspec is a good practice. See, for example, how rubygems.org uses the gemspec to display the rails gem license.

There is even a License Finder gem to help companies/individuals ensure all gems they use meet their licensing needs. This tool depends on license information being available in the gemspec. This is an important enough issue that even Bundler now generates gems with a default 'MIT' license.

I hope you'll consider specifying a license in your gemspec. If not, please just close the issue with a nice message. In either case, I'll follow up. Thanks for your time!

Appendix:

If you need help choosing a license (sorry, I haven't checked your readme or looked for a license file), GitHub has created a license picker tool. Code without a license specified defaults to 'All rights reserved'-- denying others all rights to use of the code.
Here's a list of the license names I've found and their frequencies

p.s. In case you're wondering how I found you and why I made this issue, it's because I'm collecting stats on gems (I was originally looking for download data) and decided to collect license metadata,too, and make issues for gemspecs not specifying a license as a public service :). See the previous link or my blog post aobut this project for more information.

Preserve Whitespace and Instead Configure Pygments

The .strip.chomp is removing whitespace that should allow the ability to be preserved.

It's line 41

Instead, offer the ability to preserve or pass options to pygments. http://pygments.org/docs/lexers/

gem has bad permissions

It took me a while to track this down, but all the .rb files it the 1.1.2 version of the gem have 0600 as the permissions. This basically means the gem cannot be installed site-wide because if it's owned by a user with privilege's to install site-wide, it's not readable by anyone else. I can't think of any compelling reason to not at least make the permissions 0644, but if there are any, please let me know.