Class: Syntaxi

Inherits:
Object
  • Object
show all
Defined in:
lib/syntaxi.rb

Overview

Syntaxi is a class for formatting code blocks in your HTML. It can:

  • Add line numbers

  • Wrap long lines automatically

  • Perform syntax coloring using Jamis Buck’s Syntax gem

How to Write your Code Block

In order for Syntaxi to do its magic, you’ll need to write your code blocks like this:

[code lang="ruby"]
def foo
  puts 'bar'
end
[/code]

The square bracket syntax allows Syntaxi to work seamlessly in HTML, Markdown, and Textile alike. The lang attribute specifies the language of the code block.

How to Process the Text

Having Syntaxi format your code containing the special code blocks is easy. Lets say your text is stored in text. To format this text simply do the following:

text = Syntaxi.new(text).process

Syntax coloring

If the lang attribute you specified in your opening code block tag is recognized by Jamis Buck’s Syntax gem, the block will have syntax coloring applied to it automatically. See the documentation for Syntax to learn more about how to style the different spans it produces.

Line Numbers

Syntaxi can also add line numbers to your code blocks. It can do this in two different ways:

  • Inline line numbering will add line numbers at the beginning of each line.

  • Floating line numbering will create a <div> to contain the line numbers and float that <div> left, so that selecting text from the code block will select only the code, and not the line numbers.

By default, line numbering is set to inline. To change the line number method, simply call line_number_method= like so:

Syntaxi.line_number_method = 'floating'

Valid values are ‘none’, ‘inline’, and ‘floating’

Line Wrap

Because your code blocks will often have lines that are longer than the available width, Syntaxi can wrap long lines for you. If possible the line break will done on a space. No line numbers will appear on the wrapped portions of long lines (but subsequent lines will still have the right line numbers).

By default, line wrap is enabled and wraps on column 60. To disable line wrap, simply call wrap_enabled= with false:

Syntaxi.wrap_enabled = false

To change the column on which to wrap, call wrap_at_column= like this:

Syntaxi.wrap_at_column = 70

Where to set the Options

Since the configuration options are stored as class variables, you need only change them once, and all future instances of Syntaxi will use the new values. If your entire application will use the same values, simply set the values to your liking at the beginning of execution. In Ruby on Rails, an ideal place to do this is in [RAILS_ROOT]/config/environment.rb.

Constant Summary collapse

@@line_number_method =

Specifies the line numbering method one of [none|floating|inline]

'inline'
@@wrap_enabled =

specifies whether or not to wrap long lines

true
@@wrap_at_column =

Specifies the column on which to wrap if line wrap is enabled

60

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(text) ⇒ Syntaxi

:nodoc:



117
118
119
 
# File 'lib/syntaxi.rb', line 117

def initialize(text) #:nodoc:
	@text = text
end

Class Method Details

.line_number_method=(meth) ⇒ Object

Sets the line number method. Valid values are ‘none’, ‘floating’, or ‘inline’. Default is ‘inline’

See Syntaxi class documentation for more information.



88
89
90
91
 
# File 'lib/syntaxi.rb', line 88

def self.line_number_method=(meth)
  %w{none floating inline}.include?(meth) || raise("Invalid Line Number Method. Must be one of [none|floating|inline].")
  @@line_number_method = meth
end

.wrap_at_column=(col) ⇒ Object

Sets the column on which to wrap if line wrap is enabled. Defaults to 65

See Syntaxi class documentation for more information.



110
111
112
 
# File 'lib/syntaxi.rb', line 110

def self.wrap_at_column=(col)
  @@wrap_at_column = col
end

.wrap_enabled=(enabled) ⇒ Object

Sets whether or not to wrap long lines. Defaults is true

See Syntaxi class documentation for more information.



99
100
101
 
# File 'lib/syntaxi.rb', line 99

def self.wrap_enabled=(enabled)
  @@wrap_enabled = enabled
end

Instance Method Details

#process ⇒ Object

Processes the text that this object was initialized with according to the configuration parameters.



123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/syntaxi.rb', line 123

def process
	# pick out any existing <code> blocks and replace with a placeholder
   ignores = {}
	ignore_index = 0
	@text.gsub!(/<code.*?code>/m){
		ignore_index += 1
		ignores[ignore_index] = $&
		"<!--syntaxi-code-ignore-block-" + ignore_index.to_s + "-->"
	}

	# format the specified sections
	@text.gsub!(/\[code.+?lang\s?=\s?['"](.*?)['"].*?\](.*?)\[\/code\]/m){
     language = $1
     code = $2

     # fix any spacy weirdness
     code = code.sub(/^\s*\n*/, '')
     code = code.gsub(/\t/, '  ')
     code = code.gsub(/\r\n/, "\n")

     # count the number of lines in this code block for later
     line_count = code.split("\n").length

     # do line wrapping if required
     code = wrap_long_lines(code, line_count) if @@wrap_enabled

     # do the syntax coloring
     code = Syntax::Convertors::HTML.for_syntax(language).convert(code, false)

     # do the line numbering
     code = 
       case @@line_number_method
         when 'none'
           add_no_line_numbers(code)
         when 'floating'
           add_floating_line_numbers(code, line_count)
         when 'inline'
           add_inline_line_numbers(code, line_count)
       end

     # return the code to the gsub
		code
	}

   # put the existing <code> blocks back in
	@text.gsub!(/<!--syntaxi-code-ignore-block-(\d+?)-->/) {
		ignores[$1.to_i]
	}

   # return all the processed text
   @text
end