[ANN] tagz-5.0.0

A

ara.t.howard

NAME

tagz.rb

SYNOPSIS

require Tagz

include Tagz.globally

a_:)href => "/foo"){ "bar" } #=> <a href="/foo">bar</a>

DESCRIPTION

tagz.rb is generates html, xml, or any sgml variant like a small
ninja
running across the backs of a herd of giraffes swatting of heads
like a
mark-up weedwacker. weighing in at less than 300 lines of code
tagz.rb adds
an html/xml/sgml syntax to ruby that is both unobtrusive, safe, and
available
globally to objects without the need for any builder or superfluous
objects.
tagz.rb is designed for applications that generate html to be able
to do so
easily in any context without heavyweight syntax or scoping issues,
like a
ninja sword through butter.

FEATURES

- use as a library or mixin

- simple, clean and consistent mark-up that is easy to visually
distinguish from other ruby methods

- auto-compatibility with rails/actionview

- ability to independently open and close tagz in markup

- intelligent auto-escaping of both attributes and content for both
html
and xml

- validate your html/xml with 'ruby -c' syntax check

- generally bitchin

- no lame method_missing approach that prevents tagz like 'type'
from being
generated

RAILS

in config/environment.rb

require 'tagz'

in a helper

def list_of_users
ul_:)class => 'users'){
@users.each{|user| li_{ user }}
}
end

in a view

<%=
table_{
rows.each do |row|
tr_{
row.each do |cell|
td_{ cell }
end
}
end
}
%>

in a controller

def ajax_responder
text =
tagz{
table_{
rows.each do |row|
tr_{
row.each do |cell|
td_{ cell }
end
}
end
}
}

render :text => text
end

INSTALL

gem install tagz

HISTORY
5.0.0
- introduce better escaping for attributes using xchar.rb approach
- indroduce smart escaping for content
- make Tagz.globally kick ass more hard
- note that this version is not backward compatibile if you were
relying
on tagz never escaping any content should be an ok upgrade for
most
applications

4.6.0
- fix a bug with self closing tagz that had crept in 1.0.0 ->
4.2.0. thx
jeremy hinegardner

- added tests from 1.0.0 back into svn

4.4.0
- remove dependancy on cgi lib, tagz is now completely standalone

4.3.0
- detect rails and auto-include into ActionController::Base and
include
globally into ActionView::Base

4.2.0
- general lib cleanup
- introduction of dual-mixin technique (Tagz.globally)
- few small bug fixes
- ninja tales

SAMPLES

<========< samples/a.rb >========>

~ > cat samples/a.rb

#
# in the simplest case tagz generates html using a syntax which
safely mixes
# in to any object
#

require 'tagz'
include Tagz.globally

class GiraffeModel
def link
a_:)href => "/giraffe/neck/42"){ "whack!" }
end
end

puts GiraffeModel.new.link

~ > ruby samples/a.rb

<a href="/giraffe/neck/42">whack!</a>


<========< samples/b.rb >========>

~ > cat samples/b.rb

#
# tagz.rb mixes quite easily with your favourite templating
engine, avoiding
# the need for '<% rows.each do |row| %> ... <% row.each do |
cell| %> '
# madness and other types of logic to be coded in the templating
language,
# leaving templating to template engines and logic and looping to
ruby -
# unencumbered by extra funky syntax. in rails tagz will
automatically be
# available in your erb templates.
#

require 'tagz'
include Tagz.globally

require 'erb'

rows = %w( a b c ), %w( 1 2 3 )

template = ERB.new <<-ERB
<html>
<body>
<%=
table_{
rows.each do |row|
tr_{
row.each do |cell|
td_{ cell }
end
}
end
}
%>
</body>
</html>
ERB

puts template.result(binding)


~ > ruby samples/b.rb

<html>
<body>
<table><tr><td>a</td><td>b</td><td>c</td></tr><tr><td>1</
td><td>2</td><td>3</td></tr></table>
</body>
</html>


<========< samples/c.rb >========>

~ > cat samples/c.rb

#
# once you've learned to generate html using tagz you're primed
to generate
# xml too
#

require 'tagz'
include Tagz.globally

doc =
xml_{
giraffe_{ 'large' }
ninja_{ 'small' }
}

puts doc

~ > ruby samples/c.rb

<xml><giraffe>large</giraffe><ninja>small</ninja></xml>


<========< samples/d.rb >========>

~ > cat samples/d.rb

#
# tagz.rb doesn't cramp your style, allowing even invalid html to
be
# generated. note the use of the 'tagz' method, which can be
used both to
# capture output and to append content to the top of the stack.
#

require 'tagz'
include Tagz.globally

def header
tagz{
html_
body_:)class => 'ninja-like', :id => 'giraffe-slayer')

___ "<!-- this is the header -->"
}
end

def footer
tagz{
___ "<!-- this is the footer -->"

body_
html_
}
end

puts header, footer

~ > ruby samples/d.rb

<html><body class="ninja-like" id="giraffe-slayer">
<!-- this is the header -->

<!-- this is the footer -->
<body><html>


<========< samples/e.rb >========>

~ > cat samples/e.rb

#
# tagz.rb allows a safer method of mixin which requires any tagz
methods to be
# insider a tagz block - tagz generating methods outside a tagz
block with
# raise an error if tagz is included this way. also notice that
the error is
# reported from where it was raised - not from the bowels of the
the tagz.rb
# lib.
#

require 'tagz'
include Tagz

puts tagz{
html_{ 'works only in here' }
}

begin
html_{ 'not out here' }
rescue Object => e
p :backtrace => e.backtrace
end


~ > ruby samples/e.rb

<html>works only in here</html>
{:backtrace=>["samples/e.rb:17"]}


<========< samples/f.rb >========>

~ > cat samples/f.rb

#
# tagz.rb can generate really compact html. this is great to
save bandwidth
# but can sometimes make reading the generated html a bit rough.
of course
# using tidy or the dom inspector in firebug obviates the issue;
nevertheless
# it's sometime nice to break things up a little. you can use
'tagz << "\n"'
# or the special shorthand '__' or '___' to accomplish this
#

require 'tagz'
include Tagz.globally

html =
div_{
span_{ true }
__
span_{ false } # hey ryan, i fixed this ;-)
___

___ 'foo & escaped bar'
}

puts html

~ > ruby samples/f.rb

<div><span>true</span>
<span>false</span>

foo & escaped bar
</div>


<========< samples/g.rb >========>

~ > cat samples/g.rb

# tagz gives you low-level control of the output and makes even
dashersized
# xml tagz easy enough to work with
#

require 'tagz'
include Tagz.globally

xml =
root_{
tagz__('foo-bar', :key => 'foo&bar'){ 'content' }

tagz__('bar-foo')
tagz.concat 'content'
tagz.concat tagz.escape('foo&bar')
__tagz('bar-foo')
}

puts xml


~ > ruby samples/g.rb

<root><foo-bar key="foo&amp;bar">content</foo-bar><bar-
foo>contentfoo&amp;bar</bar-foo></root>




a @ http://codeforpeople.com/
 
T

trans

=A0 =A0- no lame method_missing approach that prevents tagz like 'type' = =A0
from being
=A0 =A0 =A0generated
Click to expand...

If you are not using method_missing than I take it one can't use it to
generate arbitrary XML?

T.
 
A

ara.t.howard

If you are not using method_missing than I take it one can't use it to
generate arbitrary XML?
Click to expand...



it uses method_missing, just not in a lame way ;-)

cfp:~ > ruby -r tagz -e' include Tagz.globally; puts
anything_{ you_{ want_{ "can be generated" } } } '
<anything><you><want>can be generated</want></you></anything>


cfp:~ > ruby -r tagz -e' include Tagz.globally; raises_an_error{} '
-e:1: undefined method `raises_an_error' for main:Object (NoMethodError)



it is also very clever


cfp:~ > cat a.rb
require 'tagz'
include Tagz.globally

a = this_{ is_{ '<escaped>' } }
puts a

b = this_{ is_not_double_escaped_{ a } }
puts b



cfp:~ > ruby a.rb
<this><is>&lt;escaped&gt;</is></this>
<this><is_not_double_escaped><this><is>&lt;escaped&gt;</is></this></
is_not_double_escaped></this>


cheers.



a @ http://codeforpeople.com/
 
B

Brian Candler

Ara said:
tagz.rb is generates html, xml, or any sgml variant like a small
ninja
running across the backs of a herd of giraffes swatting of heads
like a
mark-up weedwacker.
Click to expand...

Looks interesting.

Aside: people looking at this might also be interested in HAML. Several
of your examples look very similar to how I use HAML with Sinatra.
in a helper

def list_of_users
ul_:)class => 'users'){
@users.each{|user| li_{ user }}
}
end
Click to expand...

def list_of_users
haml :_list_of_users
end

...
@@ _list_of_users
%ul{:class=>'users'}
- @users.each do |user|
%li&= user

Alternatively it can be done inline:

def list_of_users
haml <<HAML
%ul{:class=>'users'}
- @users.each do |user|
%li&= user
HAML
end
in a view

<%=
table_{
rows.each do |row|
tr_{
row.each do |cell|
td_{ cell }
end
}
end
}
%>
Click to expand...

%table
- rows.each do |row|
%tr
- row.each do |cell|
%td&= cell
in a controller

def ajax_responder
text =
tagz{
table_{
rows.each do |row|
tr_{
row.each do |cell|
td_{ cell }
end
}
end
}
}

render :text => text
end
Click to expand...

def ajax_responder
haml :_ajax_table
end

...
@@ _ajax_table
%table
- rows.each do |row|
%tr
- row.each do |cell|
%td&= cell

I can see that tagz works particularly well where you want to generate
HTML snippets directly inline with your code. The inline form of HAML is
a bit icky because it needs to align with the left-hand edge. You could
fix this with a helper, but I prefer partials because they are easily
precompiled and cached.

Regards,

Brian.
 
A

ara.t.howard

Looks interesting.

Aside: people looking at this might also be interested in HAML.
Several
of your examples look very similar to how I use HAML with Sinatra.
Click to expand...

you mean combining erb with the dsl i assume?
def ajax_responder
haml :_ajax_table
end

...
@@ _ajax_table
%table
- rows.each do |row|
%tr
- row.each do |cell|
%td&= cell

I can see that tagz works particularly well where you want to generate
HTML snippets directly inline with your code. The inline form of
HAML is
a bit icky because it needs to align with the left-hand edge. You
could
fix this with a helper, but I prefer partials because they are easily
precompiled and cached.
Click to expand...



i've used this

def unindent! s
indent = nil
s.each do |line|
next if line =~ %r/^\s*$/
indent = line[%r/^\s*/] and break
end
s.gsub! %r/^#{ indent }/, "" if indent
s
end

def unindent s
unindent! "#{ s }"
end


to get around that 'left hand side' issue.

cheers!

a @ http://codeforpeople.com/
 
B

Brian Candler

Ara said:
you mean combining erb with the dsl i assume?
Click to expand...

At a lower level, the use of hashes to represent attributes is
strikingly similar. e.g.

a_:)href => "/foo"){ "bar" }

compared to HAML:

%a{:href => "/foo"} bar
or
%a{:href => "/foo"}= "bar"

HAML lets you put any Ruby expression inside %a{...} which returns a
hash. Of course, tagz is real Ruby code, whereas HAML is its own
language.

The other thing which struck me was your use of nesting to build tables.
HAML really excels here, and the indentation-driven syntax means you
don't have to balance the closing parts. Somehow I find this more
natural for web page templates than for code.
i've used this

def unindent! s
Click to expand...

Yes, that's the sort of thing I was thinking of. HAML like this would
still need to go via a compilation phase each time it is executed,
whereas tagz is just run. Hence the benefit to keeping HAML snippets
separate and cached.

Regards,

Brian.
 
M

matt neuburg

ara.t.howard said:
it uses method_missing, just not in a lame way ;-)
Click to expand...

Not in a lame way, but in a way that means it can't be used in some
architectures. This is a very simplified version of what I'm really
doing, but it shows the problem. I'm using Builder like this:

require 'rubygems'
require 'builder'
require 'erb'

class BindingMaker
def get_binding; binding; end
def do_your_thing
s = ""
Builder::XmlMarkup.new:)target => s).div(testing)
puts s
end
def testing
"it worked"
end
end

ERB.new("<% do_your_thing %>").result(BindingMaker.new.get_binding)
#=><div>it worked</div>

I'd like to switch to Tagz here but its method_missing isn't coming back
to my BindingMaker to resolve unrecognized terminology:

require 'rubygems'
require 'tagz'
require 'erb'

class BindingMaker
def get_binding; binding; end
def do_your_thing
puts Tagz {div_ {testing()}}
end
def testing
"it worked"
end
end

ERB.new("<% do_your_thing %>").result(BindingMaker.new.get_binding)
#=> NoMethodError: undefined method 'testing' for Tagz:Module

m.
 
A

ara.t.howard

At a lower level, the use of hashes to represent attributes is
strikingly similar. e.g.

a_:)href => "/foo"){ "bar" }

compared to HAML:

%a{:href => "/foo"} bar
or
%a{:href => "/foo"}= "bar"

HAML lets you put any Ruby expression inside %a{...} which returns a
hash. Of course, tagz is real Ruby code, whereas HAML is its own
language.

The other thing which struck me was your use of nesting to build
tables.
HAML really excels here, and the indentation-driven syntax means you
don't have to balance the closing parts. Somehow I find this more
natural for web page templates than for code.
Click to expand...


gotcha.

one thing i *really* like about tagz, for real mark-up coding, is that
i can use % in vim to match open/close tags in vim (or whatever your
fav is) and also can use 'ruby -c' to validate my markup. because it
is valid ruby code you get all the ruby goodness and ruby editor
goodness for free. it was a side effect i hadn't intended when
writing it but have grown to rely on - sorta like tab completion: i
just can't go back to visually scanning to make sure xml is balanced
and correct ;-) my goal is generally to factor out enough tagz so my
erb templates fit on one screen and then i just trust tagz/ruby for
the rest.

cheers.

a @ http://codeforpeople.com/
 
M

Martin DeMello

sorta like tab completion: i just can't go back to visually scanning to m= ake
sure xml is balanced and correct ;-) =A0my goal is generally to factor ou=
Click to expand...
t

matchit.vim :)

martin
 
A

ara.t.howard

I'd like to switch to Tagz here but its method_missing isn't coming
back
to my BindingMaker to resolve unrecognized terminology:
Click to expand...

you are trying too hard ;-)


cfp:~ > cat a.rb
require 'rubygems'
require 'tagz'
require 'erb'

class BindingMaker
include Tagz.globally

def get_binding; binding; end

def do_your_thing
puts div_{ testing }
end

def testing
"it worked"
end
end

ERB.new("<% do_your_thing %>").result(BindingMaker.new.get_binding)
# <div>it worked</div>


cfp:~ > ruby a.rb
<div>it worked</div>



tagz can be used as a library, like you were using it, but in that
case you need to be explicit about the receiver. tagz is much simpler
to use in it's primary capacity - as mix-in - it is in this way that
completely POLS sgml generation and context/binding sensitivity can be
had. the binding hack traditional builders use is there precisely to
disambiguate between contexts - tagz simply avoids the issue
altogether. that's what i meant by 'lame': it's totally open, and yet
in a separate context with the builder pattern.


kind regards.



a @ http://codeforpeople.com/
 
B

Brian Candler

Ara said:
one thing i *really* like about tagz, for real mark-up coding, is that
i can use % in vim to match open/close tags in vim (or whatever your
fav is) and also can use 'ruby -c' to validate my markup. ...
i just can't go back to visually scanning to make sure xml is balanced
and correct ;-)
Click to expand...

With HAML, such validation isn't necessary: it always generates
well-formed XML, and there are no close tags to match.

You can write invalid HAML of course. The standalone 'haml' command-line
tool would probably validate it, but I haven't felt the need. My
controller tests flag if the HAML fails to compile.

What you *do* need with HAML is an editor which will indent/outdent a
block by two spaces - I use joe - but this is a commonly-needed edit
operation for Ruby code anyway.
 
M

matt neuburg

ara.t.howard said:
you are trying too hard ;-)
Click to expand...

Well, it wouldn't be the first time!
class BindingMaker
include Tagz.globally

tagz can be used as a library, like you were using it, but in that
case you need to be explicit about the receiver. tagz is much simpler
to use in it's primary capacity - as mix-in
Click to expand...

Sorry, I knew about this approach and was avoiding it. I think it was
the term "globally" that had me scared off. This usually means, uh,
globally. But thanks to your hint, I see it is just an include like any
other. So what I really want to do is more like this:

b = BindingMaker.new
class << b; include Tagz.globally; end

This way I can use Tagz in that instance of the BindingMaker and nothing
else in my universe is affected. This should be perfect! Thx for the
nudge - m.
 
A

ara.t.howard

Sorry, I knew about this approach and was avoiding it. I think it was
the term "globally" that had me scared off. This usually means, uh,
globally. But thanks to your hint, I see it is just an include like
any
other. So what I really want to do is more like this:
Click to expand...

yeah. i means 'globally' in the target scope. aka - a_{} works
outside the tagz{} context

b = BindingMaker.new
class << b; include Tagz.globally; end

This way I can use Tagz in that instance of the BindingMaker and
nothing
else in my universe is affected. This should be perfect! Thx for the
nudge - m.
Click to expand...


clever!


a @ http://codeforpeople.com/
 
A

Andrew S. Townley

Hi Ara,

FEATURES

- use as a library or mixin

- simple, clean and consistent mark-up that is easy to visually
distinguish from other ruby methods

- auto-compatibility with rails/actionview

- ability to independently open and close tagz in markup

- intelligent auto-escaping of both attributes and content for both
html
and xml

- validate your html/xml with 'ruby -c' syntax check

- generally bitchin

- no lame method_missing approach that prevents tagz like 'type'
from being
generated
Click to expand...

How does tagz handle namespaces? I have to say that what you've done
here looks very impressive, and it seems to be exactly the kind of thing
I was looking for. However, I need to make sure it has support for
namespaces, both for elements and for attributes before I can start
using it in anger.

Any examples/thoughts on how this could be done?

Cheers,

ast
 
A

ara.t.howard

How does tagz handle namespaces? I have to say that what you've done
here looks very impressive, and it seems to be exactly the kind of
thing
I was looking for. However, I need to make sure it has support for
namespaces, both for elements and for attributes before I can start
using it in anger.

Any examples/thoughts on how this could be done?

Cheers,
Click to expand...

nothing explicit, but it'd be pretty simple to make some helper
methods using this technique
=> "<foo:bar bar:foo=\"42\"/>"

i'll mull on that.

a @ http://codeforpeople.com/
 
J

James Gray

nothing explicit, but it'd be pretty simple to make some helper =20
methods using this technique

=3D> "<foo:bar bar:foo=3D\"42\"/>"

i'll mull on that.
Click to expand...

It might be neat to add some more dynamic method magic for this, like:

foo_in_bar_ { =85 }

I realize that's a bad example in case you really have a tag with that =20=

name, but you get the idea.

James Edward Gray II=
 
T

Tim Pease

It might be neat to add some more dynamic method magic for this, like:

=A0foo_in_bar_ { =85 }

I realize that's a bad example in case you really have a tag with that na= me,
but you get the idea.
Click to expand...

Set the $KCODE and use a unicode character as the separator for namespaces =
...

$KCODE =3D 'u'
foo=A6bar_('bar:foo' =3D> 42) #=3D> "<foo:bar bar:foo=3D\"42\">"


Blessings,
TwP
 
R

Ryan Davis

Set the $KCODE and use a unicode character as the separator for =20
namespaces ...

$KCODE =3D 'u'
foo=A6bar_('bar:foo' =3D> 42) #=3D> "<foo:bar bar:foo=3D\"42\">"
Click to expand...

*brain asplodes*
 
A

Andrew S. Townley

nothing explicit, but it'd be pretty simple to make some helper
methods using this technique

=> "<foo:bar bar:foo=\"42\"/>"

i'll mull on that.
Click to expand...

Thanks.

If you had to register the namespaces first in some kind of tagz
registry, maybe you could do something by handling the NameError when
you did:

foo.bar_('bar:foo' => 42)

If it had registered a namespace prefix of foo, then it'd just "do the
right thing", otherwise, you'd get the normal name error. This would
probably be the most logical syntax, but it's way beyond my Ruby magical
abilities to figure out how to actually make it work.

Still, I think it'd be the most readable of the proposed approaches...
I don't want to have to find unicode characters on my keyboard! :)

Cheers,

ast
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Similar Threads

[ANN] tagz-4.6.0 1
[ANN] tagz-4.3.0 0
[ANN] tagz-4.2.0 - giraffe slayer 9
[PATCH] tagz-5.0.0 -- processing instruction support 1
[ANN] tagz-1.0.0 0
tagz and entities 3
[ANN] xx-2.1.0 2
[ANN] fattr-5.0.0 0

Members online

No members online now.
Total: 29 (members: 2, guests: 27)
Robots: 202

Forum statistics

Threads
473,756
Messages
2,569,540
Members
45,025
Latest member
KetoRushACVFitness

Latest Threads

Top