libcaca/ruby/README

/* $Id$ */ /** \page libcaca-ruby Libcaca ruby bindings

This a Ruby binding for libcucul and libcaca.

There is no real documentation but "methods" on any object should help you :)

The classes available for libcucul are :

- Cucul::Canvas (functions that have a cucul_canvas_t* as first argument)

- Cucul::Dither (functions that have a cucul_dither_t* as first argument)

- Cucul::Font (functions that have a cucul_font_t* as first argument)
 * The constructor can currently only accept the name of a builtin font

The classes available for libcaca are :

- Caca::Display
- Caca::Event
- Caca::Event::Key
- Caca::Event::Key::Press
- Caca::Event::Key::Release
- Caca::Event::Mouse
- Caca::Event::Mouse::Press
- Caca::Event::Mouse::Release
- Caca::Event::Mouse::Motion
- Caca::Event::Resize
- Caca::Event::Quit

The character set conversion functions are not available yet in the binding.

I tried to follow Ruby spirit meaning that :
- most of the methods return self
- the methods set_foo with only an argument are also available as foo=
(returning the value instead of self)
- the methods originally named get_foo are available only as foo

What is currently available is :

\code
$ irb -rcucul
irb(main):001:0> Cucul.constants
=> ["BROWN", "BOLD", "GREEN", "LIGHTMAGENTA", "LIGHTBLUE", "BLINK",
"MAGENTA", "DEFAULT", "TRANSPARENT", "BLUE", "LIGHTRED", "DARKGRAY",
"UNDERLINE", "RED", "WHITE", "BLACK", "LIGHTCYAN", "LIGHTGRAY",
"ITALICS", "CYAN", "YELLOW", "LIGHTGREEN", "Canvas", "Dither", "Font"]
\endcode

\code
irb(main):002:0> Cucul::Canvas.methods.sort -
Cucul::Canvas.ancestors[1].methods
=> ["export_list", "import_list"]
\endcode

\code
irb(main):003:0> Cucul::Canvas.instance_methods.sort -
Cucul::Canvas.ancestors[1].instance_methods
=> ["attr=", "blit", "clear", "create_frame", "cursor_x", "cursor_y",
"dither_bitmap", "draw_box", "draw_circle", "draw_cp437_box", "draw_ellipse",
"draw_line", "draw_polyline", "draw_thin_box", "draw_thin_ellipse",
"draw_thin_line", "draw_thin_polyline", "draw_thin_triangle",
"draw_triangle", "export_memory", "fill_box", "fill_ellipse",
"fill_triangle", "flip", "flop", "frame=", "frame_count", "frame_name",
"frame_name=", "free_frame", "get_attr", "get_char", "gotoxy",
"handle_x", "handle_y", "height", "height=", "import_file",
"import_memory", "invert", "printf", "put_attr", "put_char", "put_str",
"rotate_180", "rotate_left", "rotate_right", "set_attr",
"set_boundaries", "set_color_ansi", "set_color_argb", "set_frame",
"set_frame_name", "set_handle", "set_height", "set_size", "set_width",
"stretch_left", "stretch_right", "width", "width="]
\endcode

\code
irb(main):004:0> Cucul::Font.methods.sort -
Cucul::Font.ancestors[1].methods
=> ["list"]
\endcode

\code
irb(main):005:0> Cucul::Font.instance_methods.sort -
Cucul::Font.ancestors[1].instance_methods
=> ["blocks", "height", "width"]
\endcode

\code
irb(main):006:0> Cucul::Dither.instance_methods.sort -
Cucul::Dither.ancestors[1].instance_methods
=> ["algorithm=", "algorithm_list", "antialias=", "antialias_list",
"brightness=", "charset=", "charset_list", "color=", "color_list",
"contrast=", "gamma=", "palette=", "set_algorithm", "set_antialias",
"set_brightness", "set_charset", "set_color", "set_contrast",
"set_gamma", "set_palette"]
\endcode

\code
irb(main):007:0> Caca::Display.instance_methods.sort -
Caca::Display.ancestors[1].instance_methods
=> ["get_event", "height", "mouse=", "mouse_x", "mouse_y", "refresh",
"set_mouse", "set_time", "set_title", "time", "time=", "title=", "width"]
\endcode

\code
irb(main):008:0> Caca::Event.constants
=> ["Key", "Quit", "TYPE", "Mouse", "Resize"]
\endcode

\code
irb(main):009:0> Caca::Event::Key.instance_methods - Caca::Event::Key.ancestors[1].instance_methods
=> ["ch", "utf32", "utf8"]
\endcode

\code
irb(main):010:0> Caca::Event::Key.instance_methods - Caca::Event::Mouse.ancestors[1].instance_methods
=> ["ch", "utf32", "utf8"]
\endcode

\code
irb(main):011:0> Caca::Event::Mouse.instance_methods - Caca::Event::Mouse.ancestors[1].instance_methods
=> ["button", "x", "y"]
\endcode

\code
irb(main):018:0> Caca::Event::Resize.instance_methods - Caca::Event::Resize.ancestors[1].instance_methods
=> ["w", "h"]
\endcode

And here are sample uses :

\code
$ ruby -rcucul -e 'c=Cucul::Canvas.new(6, 3).fill_box(0,0,2,2,"#"[0]);
c2=Cucul::Canvas.new(1, 1).put_str(0,0,"x"); c.blit(1,1,c2); puts
c.export_memory("irc")'
###   
#x#   
###  
\endcode

\code
$ ruby -e 'puts Cucul::Canvas.new(6,3).draw_thin_polyline([[0,0], [2,0],
[5,2],[0,0]]).export_memory("irc")' 
-.    
| `.  
----`-
\endcode

\code
$ ruby -rcucul -e 'p Cucul::Canvas.export_list'
[["caca", "native libcaca format"], ["ansi", "ANSI"], ["utf8", "UTF-8
with ANSI escape codes"], ["utf8cr", "UTF-8 with ANSI escape codes and
MS-DOS \\r"], ["html", "HTML"], ["html3", "backwards-compatible HTML"],
["irc", "IRC with mIRC colours"], ["ps", "PostScript document"], ["svg",
"SVG vector image"], ["tga", "TGA image"]]
\endcode

\code
$ ruby -rcucul -e 'p Cucul::Font.list'
["Monospace 9", "Monospace Bold 12"]
\endcode

And now a real one:

\code
require 'caca'
d = Caca::Display.new(Cucul::Canvas.new(20,10))
d.title = "Test !"
while((e = d.get_event(Caca::Event, -1)) &&
       ! e.kind_of?(Caca::Event::Quit))
    p e
    d.refresh
end
\endcode

*/