RGSS HTML DOCUMENT

#==============================================================================
# RGSS HTML DOCUMENT
# By gerkrt/gerrtunk
# Version: 1.13
# License: MIT, credits
# Date: 24/01/2011
# IMPORTANT NOTE: to acces the more actualitzed or corrected version of this
# script check here: http://usuarios.multimania.es/kisap/english_list.html
#==============================================================================


=begin


####################
#RGSS HTML DOCUMENT#
####################

This object represents a html page in memory. You can open it, write, format
and finally save to a file.

You only can write to the document throught the write methods, but you
have a plenty of them, and a few shortcuts and automtism.

For last, the html code is in a single string called contents, that can
only be readed. The save in a html file is done at the end, calling a closing
method.


#################################
#####INTRODUCTION TUTORIAL#######
#################################

1. Creating the document.

 The best way of creating the document is passing to the constructor the title
 and bgcolor (if you want to changue default ones) because it saves you a
 lot of trouble.

 Although the example uses a the name doc, you may want to short these name so
 it will be quickier to write html documents. Something like d is less readable but...

2. Basic format options.

 Define your basic formating options for the text, thats the format options
 for the core text and that will be most used. Set these options to default
 changuing the initialize method of the class(that may be nice if you only
 want to use one type of document) or call a Form method before doing nothing.

3. Changuing the text format when you need it.

 When you need to changue the format of the text for whatever reason...
 (a header, title, etc) use temporal formating. tForm method changues the format
 for a limited number of wX calls so, you can use it by default to write in
 different format a single line, or header.

4. Understanding the difference bewteen wCode, wTxt, wLine and using shortcuts.

 These are you main ways of writing to the document. wLine is thee more usefol
 for normal text writing because it appends a \n at the end of it. wTxt is like
 wLine but without the \n. Finally wCode is used to add non formated codes to the
 document, so you can add whatever you want to it.
 Each of these three methods have a shorter alias, that are wC, wT, and wL
 respecitbely.

5. Ending the document.

 It will be very rare that you need to use some other method than endSave.
 This is the better option because it  closes the document and writes it in one
 step.



##########################
#####SAMPLE EXAMPLE#######
##########################

doc = HtmlDoc.new 'log', 'Title: You can set title through constructor also', 'black'
doc.b=true
doc.wH 'Combat against King Limo', 1
doc.b=false
doc.wTable ''
doc.size=8
doc.wP 'textoooooooooooooooooooooooooo', 'center'
doc.tForm 'b,u,44,#red,Arial',4
doc.wLine 'Testing line'
doc.wBr
doc.wBr
doc.wList ['wep', 'wea', 'yu']#, type='ul', style='square'
doc.wBr 15
doc.wList [['wep', 'm'], ['wep','wea']], type='dl' #style='square'

doc.wImg 'wep.png', 'width=18 height= 22 border=5'
doc.wLink 'www.google.es', 'test'
doc.Form 'u,@blue'

doc.endSave



####################
#COMPLETE REFERENCE#
####################


CREATING A NEW HTMLDOC OBJECT

The constructor needs the html filename (accepts path, but it puts
automatically the extension .html when saving it), and accepts two extra
parameters:

Note thats recommended to use all the arguments except the charset. The other
way is more complex and slow.

title: you can pass the title of the HTML page. If you do, it will be called
the wHead method and it will asigned automatically

bgcolor: in the same way, you can set the bgcolor of the body here. This
will call the wBody method.

charset: for default it is utf8, but you can changue it.

Note that if you pass these two arguments, the creation of the starting part
of the document is more quick.


------ATRIBUTES-------

You can set or get any of these atributes:

(text atributes in html)
-b  (bold text sytle)
-u  (underlined text sytle)
-i  (italic cursive text sytle)

(font atributes in html)
-size
-name
-color (html color names or hexadecimal code)

(background colors for page or other things in html)
-bgcolor (html color names or hexadecimal code)

(the file where it will be sav ed)
-filename

You can also read the string contents, that have all the html code.


-------FORMATING--------

This object writes formated code using his owns previsously named atributes as
a marks. So, if you have the b atribute to true, it will write   each
time you write a text. It also writes all the font information that is font name,
color and size.

The way for formating a htmldoc is to changue these values each time you need
to modifiy the text format. But, for this task you have two options:

  A. You can use the atributes way, and just modifiy each time setting they.

  B. You can use the format method(Form) that interprets a string to changue the
  state of the format atributes. So, for example if you call:

  doc.Form 'b,u,13,#red,Arial'

  You are changuing all these atributes. The b, i, u, etc work in a mechanism way,
  so if its true it will be false, and if false, it will be true. The number is
  for the font size.

  Note that font colors use the special code # to mark them and bg colors use @


-------TEMPORAL FORMATING-------

Using this method(tFom) you can changue any atributes temporally, so that
they only will be aplied to the next x write methods(default=1). Note that
the methods endhtml, save, saveend, wLn, format and tformat dont reduce
the count.

doc.tForm 'b u 13 #red Arial', 3


------GENERAL WRITE METHODS------

These are. They are abreviated like wX

wLine: Writes a string of text and appends a final <br>

wH: Writes a formated header. Accepts a string name and a addiotional integer value 1-6. Note
that font size formating is skiped here. Default=2.

wTxt: Writes a formated string of text.

wList: Writes a list based on a given array. The natural is a string array,
but it forces the to_s of the object so if you have these implemented, it will
work.

You can pass two extra parameters:

type: 'dl', 'ul', 'ol' for each of the posible html lists. Default is ul.
  ul --> unordened list that uses simbols as entry marks
  ol --> here the entry marks vary to ordered numbers, letters, roman numbers, etc

style: 'square' or 'i'(and others) for each of the posible graphics for the lists. Default are
1, circle.

Note that for dl you have to pass a array of two elements arrays, like:
[[1, 'wep'], ['test', 'fooop']]

wBr: writes a single <BR>. You can also set and extra numeric argument so
it writes all that BR's.

wHr: Like the Wbr, but with <hr>

wTable(info, border=5, param='', names='', bold=true):
This method can write a table showing the values of of a rgss table with
two dimensions. Table writing is the more complex thing of these script. It haves
these parameters

  border: by default 5, it adds the atribute border width 5 to the table. This
  is vital to make the table borders visibles.

  param: this is a string that may contain any extra atributes for the table, the
  text is concatenated just before the border atribute.

  names: this is a string that defines the columns names in the table.
    names = 'a,b,c,ddddd '
    The string is splitted by , and applied in order to the columns
    col1 = 'a' col2 = 'b' col3 = 'c', etc

  bold: this boolean sets the font of the names list to bold, so it looks better.

wP(text, align): You can write a new paragraph with setting the alignement
for it. The default align is left.

wLink(link, description): Writes a html link with optional description text.
If not passed, description is the link dir.

wImg(img, width, height): Writes a image, and also you can set optionally
the width and height. Default values are 100


--------STARTING METHODS---------

wHead(title): This method  writes all the header. You have to pass
a optional string for the title of the page. The default is ''

wBody(bgcolor): This starts the body, fixing the bgcolor. If not bgcolor
is passed, it will use the atribute defined one.

Note that is better to not use this methods and send this options in the
constructor.


-------ENDING AND SAVING METHODS--------

endSave: Use this method if you just want to end a html document and save
it directly to the file. No other uses for it.

wEnd: This writes the ending of html, but it dont save it.

saveDoc: This save the document to the specified file.


-------OTHER METHODS---------

wNl: Used internally for the program. A abbreviation to append \n in some parts.
redCount: This method is called at the end of some methods and it checks and reduces
the temporal formating count.


-------SHORTED METHODS----------

wLine, wTxt and wCode have shortened methods that work like
the same:

wL : wLine
wT : WTxt
wC : wCode


-------NON FORMATED TEXT AND EXTRA CODE-----------

If you want to show a non formated text, or a add a completely yours thing
to the code, or make any other special thing, you have to use the write code
method(wCode)

This dont add any extra code to the string you pass, so its a clean way of adding
some things to the contents.


--------PASSING EXTRA ATRIBUTES TO HTML TAGS (param string)--------

You know that in html for example you can define the widht and height of a picture
or the border.

You can pass to some wMethods a extra parameter called param. This
string is addedd after the start of the html tag, so per example:

doc.wImg 'wep.png', 'width=18 height= 22 border=5'

Will result in the code :

<img src=wep.png width=18 height= 22 border=5>

Note that not all of the methods accept this. Its been implemented in
that have interesting html tags for the purpose of the script. For now they are
wImg and wTable.

Finally, the more common functions are passed as single arguments, thought you
can pass like this if you want. They are passed as signle arguments because
they are quicker to write.


--------ADDING SPECIAL FORMATINGS----------

The way of adding extra formating is calling wTxt sending the text with
the special html tags. Example:

doc.wTxt [sub] example text [/sub]


=end



#==============================================================================
# ** HtmlDoc
#------------------------------------------------------------------------------
#  This represents a Html Document in RGSS
#==============================================================================

class HtmlDoc

  attr_accessor  :b
  attr_accessor  :u
  attr_accessor  :i

  attr_accessor  :size
  attr_accessor  :color
  attr_accessor  :name

  attr_accessor  :filename

  attr_reader    :contents

  #--------------------------------------------------------------------------
  # * Object Initialization
  #--------------------------------------------------------------------------
  def initialize(filename, title='', bgcolor='', charset='utf-8')
    @filename = filename    # The name of the file. Is added +.txt later
    @contents = ""          # String that contain all the html contents
    @form_count = 0         # The counter used for temporal formating
    @count_active = false   # Mark used by the temporal formating
    @temporal_codes = ''    # This is used to save the reverse codes for temporalformating

    # HTML and font atributes and their default values
    @name = 'Arial'
    @b = false
    @u = false
    @i = false
    @size = '8'
    @color = 'black'
    @bgcolor = 'blue'

    # Write title if passed
    if title
      wHead(title)
    end

    # Write bgcolor if passed
    if bgcolor
      @bgcolor = bgcolor
      wBody
    end

    # Write charset
    if charset
      "<meta http-equiv=\"Content-Type\" content=\"text/html; charset=#{charset}\" \n"
    end

  #--------------------------------------------------------------------------
  # * wTable
  #--------------------------------------------------------------------------
  def wTable (info, border=5, param='', names='', bold=true)

    @contents+="<table border= #{border.to_s} #{param.to_s}>"

    # When is a rgss table(x,y)
    if info.is_a? Table
      # If atributes names parameter is passed
      if names
        # Split names
        splitted = names.split(',')

        # Starts a mechanism to changue bold if true and backup it
        # after the table is writed
        dont_remove_bold = false

        if bold and not @b
          @b = true
        elsif bold and @b
          dont_remove_bold = true
        end

        # Writes a first row with the atributes names
        @contents+='<tr>'
        for j in 0...info.ysize
          @contents+='<td>'
          wTxt splitted[j], false
          @contents+='</td>'
        end

        # Ends bold mechanism
        if bold and not dont_remove_bold
          @b = false
        end
      end


      # Writes the html table
      for i in 0...info.xsize
        @contents+='<tr>'
        for j in 0...info.ysize
          @contents+='<td>'
          wTxt info[i,j].to_s, false
          @contents+='</td>'
        end
      end


    end
    @contents+='</table>'
    #Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wP
  #--------------------------------------------------------------------------
  def wP (text, align='left')
    @contents += "<p align=#{align}>"
    wTxt text
    @contents += "</p>"
  end


  #--------------------------------------------------------------------------
  # * tForm
  #--------------------------------------------------------------------------
  def tForm(origcodes, count=1)
    # Active count
    @form_count = count
    @count_active = true


    temp = ''
    # Split codes to extract they
    codes = origcodes.split(',')
    # Constructs a form code that redo the temporal one
    for code in codes
      # The format functions in a mechanism way for these
      if code == 'b'
        temp += 'b'

      elsif code == 'i'
        temp += 'i'

      elsif code == 'u'
        temp += 'u'

      # For the others it have to write the font name
      elsif code.to_i.to_s == code
        temp += @size.to_s

      elsif code.include? '#'
        temp += '#'+@color

      elsif code.include? '@'
        temp += '@'+@bgcolor

      else
        temp += @name

      end
      temp+=','
    end

    # Backup that reversing codes
    @temporal_codes = temp

    # Call normal formating to apply the format
    Form origcodes

  end

  #--------------------------------------------------------------------------
  # * Form
  #--------------------------------------------------------------------------
  def Form(string)
    # Split string to extract codes
    codes = string.split(',')   #=> ["now's", "the", "time"]

    # Iterate in each code and apply it
    for code in codes
      if code == 'b'
        @b ? @b = false : @b = true

      elsif code == 'i'
        @i ? @i = false : @i = true

      elsif code == 'u'
        @u ? @u = false : @u = true

      elsif code.to_i.to_s == code
        @size = code

      elsif code.include? '#'
        @color = code

      elsif code.include? '@'
        @bgcolor = code

      else
        @name = code

      end
    end

  end



  #--------------------------------------------------------------------------
  # * wHead
  #--------------------------------------------------------------------------
  def wHead(title='')
      @contents += "<html><head><title> #{@title} </title></head> \n"

      # Check for count and reduce it
      redCount
  end

  #--------------------------------------------------------------------------
  # * wCode
  #--------------------------------------------------------------------------
  def wCode(code)
    @contents += code

    # Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wC
  #--------------------------------------------------------------------------
  def wC(code)
    wCode(code)
  end

  #--------------------------------------------------------------------------
  # * wBr
  #--------------------------------------------------------------------------
  def wBr(num=1)
    num.times{|i|@contents += '<br>'}
    wNl

    # Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wHr
  #--------------------------------------------------------------------------
  def wHr(num=1)
    num.times{|i|@contents += '<hr>'}
    wNl

    # Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wNl
  #--------------------------------------------------------------------------
  def wNl
    @contents += "\n"
  end

  #--------------------------------------------------------------------------
  # * wH
  #--------------------------------------------------------------------------
  def wH(text, num=2)
    @contents += " <h#{num.to_s}> "
    @contents += text
    @contents += " </h#{num.to_s}> <br> \n "

    # Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wBody
  #--------------------------------------------------------------------------
  def wBody(bgcolor='')
      if bgcolor
        @contents += "<body bgcolor=#{bgcolor}> \n"
      else
        @contents += "<body bgcolor=#{@bgcolor}> \n"
      end

    # Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wList
  #--------------------------------------------------------------------------
  def wList(array, type='ol', style='1')
    # Set the entry mark text based on the list type pased
    if type=='ol'
      entry='li'

    elsif type=='dl'
      entry='dt'

    end

    # Start list
    @contents += "<#{type} type=#{style} >"

    # Write each entry
    for o in array
      # If its ol or li
      if type == 'ol' or type == 'li'
        @contents += "<#{entry}>"
        wTxt(o.to_s)
        @contents += "</#{entry}>"

      else
      # If its a dictionary
        @contents += "<#{entry}>"
        wTxt(o[0].to_s)
        @contents += "</#{entry}>"

        @contents += "<dd>"
        wTxt(o[1].to_s)
        @contents += "</dd>"
      end
    end

    # End list
    @contents += "</#{type}>"

    # Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wImg
  #--------------------------------------------------------------------------
  def wImg(img_source, param='')
    @contents += "<img src=#{img_source} #{param} >"
    wBr
    wNl

    # Check for count and reduce it
    redCount
  end

  #--------------------------------------------------------------------------
  # * wLink
  #--------------------------------------------------------------------------
  def wLink(link, reftext='')
    @contents += "<a href=#{link}> #{reftext} </a>"
    wBr
    wNl

    # Check for count and reduce it
    redCount
  end


  #--------------------------------------------------------------------------
  # * wLine
  #--------------------------------------------------------------------------
  def wLine(line)
    wTxt(line)
    @contents += '<br>'
  end

  #--------------------------------------------------------------------------
  # * wL
  #--------------------------------------------------------------------------
  def wL(line)
    wLine(line)
  end

  #--------------------------------------------------------------------------
  # * wTxt
  #--------------------------------------------------------------------------
  def wTxt(txt, reduce_count=true)
    # Line start
    @contents  = "<font face=#{@name} size=#{@size.to_s} color=#{@color}> "

    if @b
      @contents += '<b>'
    end

    if @i
      @contents += '<i>'
    end

    if @u
      @contents += '<u> '
    end


    # Write txt variable

    @contents += txt

    # Line end
    if @u
      @contents += ' </u>'
    end

    if @i
      @contents += '</i>'
    end

    if @b
      @contents += '</b>'
    end

    @contents += " </font>\n"

    # Check for count and reduce it
    redCount if reduce_count
  end

  #--------------------------------------------------------------------------
  # * wT
  #--------------------------------------------------------------------------
  def wT(txt)
    wTxt (txt)
  end

  #--------------------------------------------------------------------------
  # * wEnd
  #--------------------------------------------------------------------------
  def wEnd
    @contents += '</body></html>'
  end

  #--------------------------------------------------------------------------
  # * saveDoc
  #--------------------------------------------------------------------------
  def saveDoc
    file = open(@filename + '.html',  'w')
    file.write(@contents)
    file.close
  end

  #--------------------------------------------------------------------------
  # * endSave
  #--------------------------------------------------------------------------
  def endSave
    @contents += '</body></html>'
    file = open(@filename + '.html',  'w')
    file.write(@contents)
    file.close
  end

  #--------------------------------------------------------------------------
  # * redCount
  #--------------------------------------------------------------------------
  def redCount

    # If its the last count and active, call redo format and end all
    if @form_count-1 == 0 and @count_active
      @count_active = false
      # Reverse temporal format calling the saved redo code
      Form @temporal_codes
      @temporal_codes = ''

    # If not reduce count and active
    elsif @count_active
      @form_count-=1
    end

  end
end