html-table 1.7.0 → 1.7.1

data/doc/attributes.md

@@ -0,0 +1,160 @@
+## Description
+   A list of attributes handled by html-table.  Each of the writers has a
+   corresponding reader unless otherwise stated.
+
+## Attributes
+`abbr=(string)`
+
+Sets the value for the abbr attribute.
+
+`align=(string)`
+
+Sets the align attribute. Valid arguments are 'left', 'center' and
+'right'.  An ArgumentError is raised if an invalid argument is passed.
+
+`axis=(string)`
+
+Sets the value for the axis attribute.
+
+`background=(url)`
+
+Sets the background attribute. The url must be a String or a TypeError
+is raised. This is a non-standard extension.
+
+`bgcolor=(color)`
+
+Sets the color for the bgcolor attribute. Hex values should still be
+quoted, e.g. "#F80000".
+
+`border=(num)`
+
+Sets the value for the border attribute.
+
+`bordercolor=(color)`
+
+Sets the color for the bordercolor attribute. This is a non-standard extension.
+
+`bordercolordark=(color)`
+
+Sets the color for the bordercolordark attribute. This is a non-standard extension.
+
+`bordercolorlight=(color)`
+
+Sets the color for the bordercolorlight attribute. This is a non-standard extension.
+
+`cellpadding=(num)`
+
+Sets the value for the cellpadding attribute.  Raises an ArgumentError if num.to_i is less than 0.
+
+`cellspacing=(num)`
+
+Sets the value for the cellspacing attribute.  Raises an ArgumentError if num.to_i is less than 0.
+
+`char=(character)`
+
+Sets the value for the char attribute.  An ArgumentError is raised if the
+argument passed has a length greater than 1 (i.e. it may only be a char).
+
+`charoff=(value)`
+
+Sets the value for the charoff attribute.
+
+`colspan=(num)`
+
+Sets the colspan attribute.
+
+`content=(*args)`
+
+The behavior of this method varies largely based on the type of instance
+that invokes it. Here are the rules for each argument in `args`:
+    
+* `Table`:
+    
+If `arg` is a `Row`, `Head`, `Foot`, `Body` or `ColGroup` object, it is
+pushed onto the table. If `arg` is a string, one `Row` object with
+one one `Data` object is pushed onto the `Table`. If `arg` is an `Array`,
+then one `Row` object is created and each element of the array is pushed
+onto that Row.
+    
+* `Table::Row`:
+    
+If `arg` is a `Header` or `Data` object, it is pushed onto the `Row`. If
+`arg` is a `String`, it is created as a single `Data` object. Any attempt
+to assign any other type will raise a `TypeError`.
+       
+* `Table::Head`, `Table::Foot`, `Table::Body`:
+    
+Behave identically to `Table::Row` except that they accept Table::Row objects as well.
+       
+* `Table::ColGroup`:
+    
+Behaves identically to Table::Row except that it only accepts Col objects.
+       
+* `Table::Col`:
+    
+This method is undefined for Table::Col, because they do not accept content.
+       
+* `Table::Data and Table::Header`:
+    
+Sets the text string for the `Data` or `Header` object. Arrays are join'd.
+Any other type raises a `TypeError`.
+
+`frame=(type)`
+
+Sets the value for the frame attribute. Valid values are border, void,
+above, below, hsides, lhs, rhs, vsides, and box. An ArgumentError is
+raised if an invalid type is detected.
+
+`height=(num)`
+
+Sets the value for the height attribute. Raises an ArgumentError if
+num.to_i is less than 0.
+
+`hspace=(num)`
+
+Sets the value for the hspace attribute. Raises an ArgumentError if
+num.to_i is less than 0.
+
+`nowrap=(bool)`
+
+Sets the value for the nowrap attribute. Setting it to true means it will be
+included as an attribute for the Table object. The default is false (i.e. not included).
+
+`rowspan=(num)`
+
+Sets the value for the rowspan attribute.
+
+`rules=(edges)`
+
+Sets the value for the rules attribute. Valid values are "all", "groups",
+"rows", "cols", or "none". An `ArgumentError` is raised if an invalid edges value
+is detected.
+
+`scope=(scope)`
+
+Sets the value for the scope attribute.  Valid values for +scope+ are
+row, col, rowgroup or colgroup.  An ArgumentError is raised if an invalid
+scope value is passed.
+
+`span=(num)`
+
+Sets the span attribute. If num.to_i is less than 0, and ArgumentError is raised.
+
+`summary=(string)`
+
+Sets the value for the summary attribute.
+
+`valign=(position)`
+
+Sets the value for the valign attribute. Valid values are top, center,
+bottom, and baseline. This is a non-standard extension.
+
+`vspace=(num)`
+
+Sets the value for the vspace attribute. This is a non-standard extension.
+
+`width=(num)`
+
+Sets the value for the width attribute.  If num is in 'x%' format, it
+is retained as a string.  If num is a Fixnum (or stringified number), an
+ArgumentError is raised if num.to_i is less than 0.

data/doc/table.md

@@ -0,0 +1,173 @@
+## Description
+An interface for generating HTML Tables with Ruby.
+
+## Synopsis
+```ruby
+require "html/table"
+include HTML
+
+table = HTML::Table.new{ |t|
+  t.border  = 1
+  t.bgcolor = "red"
+}
+
+table.push Table::Row.new{ |r|
+  r.align   = "left"
+  r.bgcolor = "green"
+  r.content = ["foo","bar","baz"]
+}
+
+row = Table::Row.new{ |r|
+  r.align   = "right"
+  r.bgcolor = "blue"
+  r.content = "hello world"
+}
+
+table[1] = row
+
+puts table.html
+
+#### output ####
+<table border=1 bgcolor='red'>
+  <tr align='left' bgcolor='green'>  # row 0
+     <td>foo</td>                    # column 0
+     <td>bar</td>                    # column 1
+     <td>baz</td>                    # column 2
+  </tr>
+  <tr align='right' bgcolor='blue'>  # row 1
+     <td>hello world</td>            # column 0
+  </tr>
+</table>
+```
+
+See the 'examples' directory for more examples.
+
+## Mixins
+`Table` is a subclass of `Array`, and therefore mixes in `Enumerable`. The
+`push`, `unshift` and `[]=` methods have been modified. See below for details.    
+    
+Table also mixes in the `AttributeHandler` module which provides methods
+for adding attributes to each of the tag types. See attributes.md for
+more details.
+
+## Constants
+`VERSION`
+
+The current version number (a String). This serves as the VERSION number
+for the entire html-table package.
+
+## Class Methods
+```
+Table.new(arg=nil)
+Table.new(arg=nil){ |t| ... }
+```
+
+Creates a new Table instance.  You can set attributes for the Table by
+passing a block.
+    
+If `arg` is supplied, it is automatically interpreted to be content. This
+is a shortcut for `Table.new{ |t| t.content = '...' }`.
+
+`Table.global_end_tags?`
+
+Returns the value of the `global_end_tags` class variable.  By default,
+this is true.
+
+`Table.global_end_tags=(true|false)`
+
+Sets the `global_end_tags` class variable. This determines class-wide, for
+those classes where end tags are optional, whether or not end tags are
+included in the final html. Classes where end tags are not optional are
+not affected.
+    
+If set to false, this overrides individual class end tags settings.
+
+## Instance Methods
+`Table#[]=(index, object)`
+
+Assigns `object` to `index`. There are restrictions to the data
+types that you can assign to a Table instance. They include `Caption`,
+`ColGroup`, `Body`, `Foot`, `Head` and `Row`. You cannot assign a slice (yet).
+
+`Table#configure(row_num, col_num=0){ |td_object| block }`
+
+Configures column `col_num` at row `row_num`, using a block to set
+options. If only `row_num` is specified, then you'll be configuring
+only the row. Generally speaking, that means you'll be configure a
+Table::Row and not a Data or Header object.
+
+`Table#content`
+
+Returns the HTML content.
+
+`Table#content=(arg)`
+
+Adds data to the Table. The `arg` may be a Table::Row object, an
+Array of Table::Row objects, an Array of Array's, an Array of Strings,
+or a single String. In the last two cases, a single Table::Row with a
+single Table::Row::Data object is created, with the string as the content.
+
+`Table#html`
+
+Returns the entire HTML content for the Table Object. This is what you
+want to print when you're done creating your Table.
+
+`Table#push(obj)`
+
+Pushes `obj` onto the Table, where `obj` must be a Row, Caption,
+ColGroup, Body, Foot or Head object. Also note that the Caption and Head
+objects will automatically put themselves at row 0 (or possibly 1, in the
+case of a Head object where a Caption already exists).
+
+`Table#unshift(obj)`
+
+Unshifts `obj` onto the Table. The same rules apply to `unshift` as
+they do to `push`.
+
+## Notes
+A Table consists of Table::Row, Table::Caption, Table::ColGroup,
+Table::Body, Table::Foot, Table::Head and Table::Row objects.
+
+Table::Row objects in turn consist of Table::Row::Data and Table::Row::Header objects.
+
+Table::ColGroup objects consist of Table::ColGroup::Col objects.
+
+Table::Head, Table::Body and Table::Foot objects consist of Table::Row objects.
+
+String attributes are quoted. Numeric attributes are not.
+
+Some attributes have type checking. Some check for valid arguments. In
+the latter case, it is case-insensitive. See the documentation on
+specific methods for more details.
+
+Using a non-standard extension (e.g. "background") will send a warning to
+STDERR in `$VERBOSE` (-w) mode.
+
+## Known Bugs
+None that I'm aware of. Please report bugs on the project page at
+https://github.com/djberg96/html-table
+
+## Future Plans
+Allow standard html tags to be added to elements as appropriate, such
+as `<B>`, `<I>`, etc.
+
+CSS support.
+
+## Acknowledgements
+Anthony Peacock, for giving me ideas with his HTML::Table Perl module.
+Holden Glova and Culley Harrelson for API suggestions and comments.
+
+## License
+Apache-2.0
+
+## Copyright
+(C) 2003-2021 Daniel J. Berger
+All Rights Reserved
+
+## Warranty
+This package is provided "as is" and without any express or
+implied warranties, including, without limitation, the implied
+warranties of merchantability and fitness for a particular purpose.
+
+## Author
+Daniel J. Berger

data/doc/table_body.md

@@ -0,0 +1,9 @@
+## Description
+A Table::Body object represents a single `<TBODY></TBODY>` instance for an HTML Table.
+
+## Notes
+In virtually every respect the Table::Body class is identical to
+the Table or Table::Row class. Unlike Table::Foot or Table::Head, there
+can be more than one instance (i.e. it's not a singleton class).
+    
+A Table::Body contains Table::Row objects.

data/doc/table_caption.md

@@ -0,0 +1,10 @@
+## Description
+A Table::Caption object represents a single `<CAPTION></CAPTION>` instance
+for an HTML Table.
+
+## Notes
+The Table::Caption class is virtually identical to the Table::Row::Data
+class. There is one important behavioral difference, however. First,
+there can only be one Table::Caption. If you attempt to add a second one,
+it will merely overwrite the existing one. Second, a Table::Caption is
+always bumped to index 0.

data/doc/table_colgroup.md

@@ -0,0 +1,8 @@
+## Description
+A Table::ColGroup object represents a single `<COLGROUP></COLGROUP>`
+instance for an HTML Table.
+
+## Notes
+In virtually every respect the Table::ColGroup class is identical to the
+Table::Row class.  The only difference, beyond the begin and end tags, is
+that a ColGroup may only contain instances of the Col class.

data/doc/table_colgroup_col.md

@@ -0,0 +1,7 @@
+## Description
+A Table::ColGroup::Col object represents a single `<COL>` instance for an HTML Table.
+
+## Notes
+In virtually every respect the Table::ColGroup::Col class is identical to
+the Table::Row::Data class. The only differences are that a Table::ColGroup::Col
+instance does not contain any content, nor does it include an end tag.

data/doc/table_content.md

@@ -0,0 +1,17 @@
+## Description
+A Table::Content is a wrapper for content used for Table::Row::Data and
+Table::Row::Header objects.  Although it can be instantiated directly, in
+practice it is autogenerated for you.
+
+## Notes
+Table::Content is a subclass of String and was mostly created in order
+to support a DSL style syntax as well as physical tags.
+
+## Synopsis
+```ruby
+content = Table::Content.new('my content') do
+  bold        true
+  italics     true
+  underline   true
+end
+```

data/doc/table_foot.md

@@ -0,0 +1,8 @@
+## Description
+A Table::Foot object represents a single `<TFOOT></TFOOT>` instance for an HTML Table.
+
+## Notes
+In virtually every respect the Table::Foot class is identical to the
+Table or Table::Row class. There is one significant difference. The
+Table::Foot class is a singleton. There can be only one Table::Foot
+instance per table.

data/doc/table_head.md

@@ -0,0 +1,10 @@
+## Description
+A Table::Head object represents a single `<THEAD></THEAD>` instance for an HTML Table.
+
+## Notes
+In virtually every respect the Table::Head class is identical to
+the Table or Table::Row class. There are two significant differences.
+First, the Table::Head class is a singleton. There can be only one
+Table::Head instance per table. Second, if an instance of Table::Head
+is added to a table, it will be automatically be put at index 0 (or 1
+if a Table::Caption exists).

data/doc/table_row.md

@@ -0,0 +1,114 @@
+## Description
+A Table::Row object represents a single <TR></TR> instance for an HTML
+Table. Although it is nested under Table, it is not a subclass of Table.
+It is, however, a subclass of Array.
+
+## Synopsis
+```ruby
+require "html/table"
+include HTML
+
+table = HTML::Table.new
+
+row1 = Table::Row.new{ |r|
+  r.align   = "left"
+  r.bgcolor = "green"
+  r.content = ["foo","bar","baz"]
+}
+
+row2 = Table::Row.new{ |r|
+  r.align   = "right"
+  r.bgcolor = "blue"
+  r.content = "hello world"
+}
+
+table.push row1, row2
+
+row1.content = "foofoo"
+row1.configure(3){ |d| d.bgcolor = "pink" }
+
+row1.push Table::Row::Header.new{ |h|
+  h.colspan = 2
+  h.content = "This is a table header"
+}
+
+row2.push Table::Row::Header.new{ |h|
+  h.colspan = 2
+  h.content = "This is also a table header"
+}
+
+puts table.html
+#### output ####
+```
+```html
+<table>
+  <tr align='left' bgcolor='green'>
+     <td>foo</td>
+     <td>bar</td>
+     <td>baz</td>
+    <td bgcolor='pink'>foofoo</td>
+     <th colspan=2>This is a table header</th>
+  </tr>
+  <tr align='right' bgcolor='blue'>
+    <td>hello world</td>
+     <th colspan=2>This is also a table header</th>
+  </tr>
+</table>
+```
+
+See the 'examples' directory for more examples.
+
+## Mixins
+Table::Row is a subclass of Array and therefore mixes in Enumerable.  It
+also mixes in Attribute_Handler.
+
+## Class Methods
+```
+Table::Row.new(arg=nil)
+Table::Row.new(arg=nil){ |t| ... }
+```
+
+Creates a new table. You can set attributes for the TableRow by passing a block.
+    
+If `arg` is supplied, it is automatically interpreted to be content.
+This is a shortcut for Table::Row.new{ |r| r.content = '...' }.
+
+## Instance Methods
+`Table::Row#[]=(index, obj)`
+
+Assigns `obj` to index. The `obj` must be a Table::Row::Header or
+Table::Row::Data object, or a TypeError is raised.
+
+Table::Row#content
+Returns the HTML content of the TableRow instance, i.e. the stuff between
+the `<TR>` and `</TR>` tags.
+
+`Table::Row#content=(args)`
+
+Because a Table::Row doesn't store any of its own content, the arguments
+to this method must be a Table::Row::Data object, a Table::Row::Header
+object, or a String (or an array of any of these). In the latter case,
+a single Table::Row::Data object is created for each string.
+
+`Table::Row#html`
+
+Returns the entire HTML content of the TableRow instance.
+
+`Table::Row#push(obj)`
+
+Pushes `obj` onto the Table::Row. The +obj+ must be a Table::Row::Data
+or Table::Row::Header object, or a TypeError is raised.
+
+`Table::Row#unshift(obj)`
+
+Unshifts +obj+ onto the Table::Row. The same rules for push apply
+to unshift as well.
+
+## Notes
+String attributes are quoted. Numeric attributes are not.
+
+Some attributes have type checking. Some check for valid arguments. In
+the latter case, it is case-insensitive.
+
+Using a non-standard extension (e.g. "background") will send a warning to
+STDERR in $VERBOSE (-w) mode.

data/doc/table_row_data.md

@@ -0,0 +1,100 @@
+## Description
+A Table::Row::Data object represents a single <TD></TD> instance for an HTML
+Table. For purposes of html-table, it also represents a "column".
+
+## Synopsis
+```ruby
+require "html/table"
+require HTML
+
+Table::Row.end_tags = false
+Table::Row::Data.end_tags = false
+
+table = Table.new{ |t| t.border = 1 }
+row = Table::Row.new
+
+col1 = Table::Row::Data.new{ |d|
+  d.abbr    = "test"
+  d.align   = "right"
+  d.content = "hello world"
+}
+
+col2 = Table::Row::Data.new{ |d|
+  d.align   = "center"
+  d.content = "Matz rules!"
+}
+
+col3 = Table::Row::Data.new{ |d|
+  d.align   = "left"
+  d.content = "Foo!"
+}
+
+row.push col1, col2, col3
+
+puts table.html
+```
+
+output:
+
+```html
+<table border=1>
+  <tr>
+    <td abbr='test' align='right'>hello world
+    <td align='center'>Matz rules!
+    <td align='left'>Foo!
+</table>
+```
+
+See the 'examples' directory under 'doc' for more examples.
+
+## Mixins
+Table::Row::Data mixes in Attribute_Handler.    
+
+## Class Methods
+```
+Table::Row::Data.new(arg=nil)
+Table::Row::Data.new(arg=nil){ |t| ... }
+```
+Creates a new table.  You can set attributes for the Table::Row::Data by passing a block.
+   
+If `arg` is supplied, it is automatically interpreted to be content.
+This is a shortcut for Table::Row::Data.new{ |d| d.content = '...' }.
+
+`Table::Row::Data.end_tags`
+
+Returns true or false to indicate whether end tags are included or not.
+
+`Table::Row::Data.end_tags=(bool)`
+
+Sets whether or not end tags are included in the html.
+
+`Table::Row::Data.indent_level`
+Returns the current number of spaces that `<TD>` tags are indented. The default is 6.
+
+`Table::Row::Data.indent_level=(num)`
+
+Sets the number of spaces that `<TD>` tags are indented.
+
+## Instance Methods
+TableData#content
+
+Returns the content of the TableData object, i.e. the stuff between `<TD>` and `</TD>`.
+
+Table::Row::Data#content=(string)
+
+Sets the content for the TableData object, i.e. the stuff between `<TD>` and `</TD>`.
+
+Table::Row::Data#html
+
+Returns all html content for the TableData instance.
+
+## Notes
+The end tags for Table::Row::Data objects are are the same line as the begin tags.
+    
+String attributes are quoted. Numeric attributes are not.
+
+Some attributes have type checking. Some check for valid arguments. In
+the latter case, it is case-insensitive.
+
+Using a non-standard extension (e.g. "background") will send a warning to
+STDERR in $VERBOSE (-w) mode.

data/doc/table_row_header.md

@@ -0,0 +1,6 @@
+## Description
+A Table::Row::Header object represents a single `<TH></TH>` instance for an HTML Table.
+
+## Notes
+The Table::Row::Header class is identical in every way to the
+Table::Row::Data class, except for the begin and end tags.

data/examples/simple1.rb

@@ -9,13 +9,15 @@ require 'html/table'
 include HTML
 
 table = Table.new{ |t|
-   t.content = [
-      %w/foo bar baz/,
-      %w/1 2 3/,
-      %w/hello world/
-   ]
+  t.content = [
+    %w[foo bar baz],
+    %w[1 2 3],
+    %w[hello world]
+  ]
 }
 
+#Table.global_end_tags = false
+
 puts table.html
 
 =begin