README

= Hoshi

== Summary

Hoshi is a library for creating real, first-class HTML/XML views.  It is a
generator, so unlike template libraries, you can take advantage of mixins,
inheritance, and all the other wonderful features of Ruby's object system.

In addition to HTML5 and plain XML, Hoshi supports RSS2 and SVG, as well as some
older standards like HTML4 and XHTML1.  (If you need anything more specific, it
is easy to extend, and if you want to contribute, patches are welcome.)

Hoshi is designed to:
	* Generate clean HTML/XML with minimal effort
	* Be simple, to avoid bugs and keep it easy to use, understand, and modify
	* Take full advantage of Ruby's object sytem
	* Be more readable and easier to write than bare HTML

It was initially inspired by (and partially modeled on) Markaby, but the
implementation is more straightforward so the semantics are cleaner (e.g., no
instance_eval, meaning scope inside blocks supplied to tags has no gotcha's).

See doc/LICENSE for the license, doc/examples for examples.  See test/ for the
tests, and run `rake test` to execute them.  (The tests take a fraction of a
second to execute.)

== Installation

You can install via rubygems,

  gem install hoshi

or by downloading from github (http://github.com/pete/hoshi).

== Usage

These examples 
Also, there is a program included called html2hoshi (and associated
lib/html2hoshi.rb; see Hoshi.from_html) that takes HTML as input and
converts it to Ruby code using Hoshi.

=== Class-based

These should be fairly straightforward:

  require 'hoshi'

  class Trivial < Hoshi::View :html5
    def show
      doctype
      html {
        head {
          title "Hello, world!"
          link rel: 'stylesheet', href: '/css/hoshi.css'
        }

        body {
          h1 "Hello, world!"
          p "This is a greeting to the world."
        }
      }
      render
    end
  end

  puts Trivial.new.show

You can get a little more complicated:

  require 'hoshi'
  require 'cgi'

  module Layout
    def main_page(t)
      doctype
      html {
        head {
          title t
          script(type: 'text/javascript') {
            raw "alert(\"Hi, I'm some javascript, I suppose.\");"
          }
        }
        
        body {
          h1 t, class: 'page_title'

          yield
        }
      }
    end

    def list_page(t)
      main_page(t) {
        ul {
          yield
        }
      }
    end
  end

  class Fibonacci < Hoshi::View :xhtml1
    include Layout

    def list_page(n)
      super("Fibonacci: f(0)..f(#{n})") {
        fib_upto(n).map { |i| li i.to_s }
      }
      CGI.pretty(render)
    end

    private

    def fib_upto n
      a = Array.new(n) 
      
      0.upto(n) { |i|
        a[i] = 
          if i < 2
            1
          else
            a[i - 1] + a[i - 2]
          end
      }

      a
    end
  end

  puts Fibonacci.new.list_page(n)

=== Block-based

For simpler cases where you just need to produce a little markup.  Useful for
small scripts.

  require 'hoshi'

  str = Hoshi::View::HTML5.build {
    doctype
    html {
      head {
        title "Hello, world!"
        link rel: 'stylesheet', href: '/css/hoshi.css'
      }

      body {
        h1 "Hello, world!"
        p "This is a greeting to the world."
      }
    }
  }

  puts str

== Bugs

There needs to be some work done on correcting the tags; I suspect I'm missing
or miscategorizing some of them.  If you come across a case where Hoshi emits
invalid HTML/XML/etc., please let me know.

That's the only known bug likely to affect you.  See doc/TODO for a more
detailed roadmap.

== Credits

Author:
Pete Elmore, Rekka Labs -- ( pete(a)debu.gs )

The initial design is pretty heavily indebted to:
_why the lucky stiff's Markaby library

Simple block version:
Nolan Darilek -- (nolan(a)thewordnerd.info)

Friends that have reported bugs:
Lars Lethonen, opsangeles -- ( http://opsangeles.com/ )
Hunter, Spore Labs -- ( https://github.com/madhermit )

The guys that paid me to do the initial version:
AT&T Interactive.  (Now yp.com; they have changed names and owners.)

The company that covers development now:
Rekka Labs -- http://rekka.io/  (Yes, you can hire us.)

Also, I guess I should credit Attractive Eighties Women
(http://attractiveeightieswomen.com/), since I was blasting them the
whole time I was developing this.  Like, over and over.  I couldn't stop
listening.

== Home page

http://debu.gs/hoshi