# module Tioga::Tutorial::DocStructure

# The basic anatomy of a tioga document: “sample.rb”¶ ↑

Source files for tioga are Ruby programs of a particular form and content.

The overall form is described in this section.

Some details of the content are discussed in the rest of the tutorial.

We'll use a very simple case to illustrate the general form: a file that defines two figures, one that fills the frame with blue and one that fills it with red. The file will define a class, “MyFigures”, and create an instance of it. We'll start with those operations, then add bit-by-bit until we have a complete definition.

    class MyFigures

    end

    MyFigures.new

We start adding the missing pieces by requiring rubygems (`require' tells Ruby to load the required item if it hasn't already been loaded). The rubygems package is the Ruby standard for managing add-on software libraries. Once you've done the “require rubygems” command, the following require command for the tioga `FigureMaker` will work whether tioga was downloaded as a gem or independently.

    >> require 'rubygems'
    >> require 'Tioga/FigureMaker'

       class MyFigures

       end

       MyFigures.new

Here we are using “>>” to mark the newly added lines. At the end, we'll give a complete listing without any of those marks which are not really part of the code.

Next we'll `include' the `Tioga` and `FigureConstants` modules to make it easy to reference the methods and attributes they define – include makes everything defined in the module available as if defined here.

       require 'rubygems'
       require 'Tioga/FigureMaker'

       class MyFigures

    >>     include Tioga
    >>     include FigureConstants

       end

       MyFigures.new

The default tioga `FigureMaker` will be doing the work for us, so our initialize method will get it and put it in an instance variable for us that we'll name “@figure_maker” (the “@” is Ruby's way of saying that this is an attribute associated with a particular object). The various tioga user interfaces will also be talking to the default `FigureMaker` to find out what figures we've defined and ask for various ones to be created in response to our commands.

       require 'rubygems'
       require 'Tioga/FigureMaker'

       class MyFigures

           include Tioga
           include FigureConstants

    >>     def initialize
    >>         @figure_maker = FigureMaker.default
    >>     end

       end

       MyFigures.new

The “MyFigures.new” command is asking Ruby to create an instance of the MyFigures class which in turn involves Ruby calling the class's initialize routine. The command does NOT automatically make the figures at the time the class object is created. The figures get constructed in response to user requests that will be forwarded from the user interface to the figure maker and then on to our routines.

But all that comes later. For now, our next step is to add a method called “t” that simply returns the local attribute @figure_maker. Then we can use “t.” to talk to our instance of the `FigureMaker` rather than having to type “@figure_maker” all the time.

The “.” in “t.” is part of the “object.name” idiom in Ruby. It refers to the named attribute or method in the given object. In turn, the object can come from some other evaluation. In the “t.” case, our method called “t” will return the object we've saved in our local attribute called “@figure_maker”.

       require 'rubygems'
       require 'Tioga/FigureMaker'

       class MyFigures

           include Tioga
           include FigureConstants

    >>     def t
    >>         @figure_maker
    >>     end

           def initialize
               @figure_maker = FigureMaker.default
           end

       end

       MyFigures.new

When we write something like “t.line_width”, we're talking about the thing referenced by the name “line_width” in the object that is returned by evaluating our method called “t”. It sounds complicated, but you can safely forget the details and just remember this:

  “t.” is talking to `Tioga`.

The next step is to add to the initialize routine to tell the `FigureMaker` about the figures defined in this file. That is done by calling “def_figure” for each one, giving a string name and a body of code that will produce the figure. The names are “Blue” and “Red”, and the command bodies are given inside the curly braces. In this case the commands are simply calls on methods with the corresponding name, but in lowercase since all method names begin with lowercase (Ruby is picky about that).

       require 'rubygems'
       require 'Tioga/FigureMaker'

       class MyFigures

           include Tioga
           include FigureConstants

           def t
               @figure_maker
           end

           def initialize
               @figure_maker = FigureMaker.default
    >>         t.def_figure('Blue') { blue }
    >>         t.def_figure('Red') { red }
           end

       end

       MyFigures.new

The figures are defined to call routines “blue” and “red”, so we'll add those next.

       require 'rubygems'
       require 'Tioga/FigureMaker'

       class MyFigures

           include Tioga
           include FigureConstants

           def t
               @figure_maker
           end

           def initialize
               @figure_maker = FigureMaker.default
               t.def_figure('Blue') { blue }
               t.def_figure('Red') { red }
           end

    >>     def blue
    >>         t.fill_color = Blue
    >>         t.fill_frame
    >>     end

    >>     def red
    >>         t.fill_color = Red
    >>         t.fill_frame
    >>     end

       end

       MyFigures.new

We could use the file as it is now, but I like to have the output files go in a subfolder rather than cluttering up the top level folder where the definition file lives. We can specify a “save directory” by setting the `FigureMaker` “save_dir” attribute. That will be our last addition. Here's the final version of “sample.rb”.

    require 'rubygems'
    require 'Tioga/FigureMaker'

    class MyFigures

        include Tioga
        include FigureConstants

        def t
            @figure_maker
        end

        def initialize
            @figure_maker = FigureMaker.default
            t.def_figure('Blue') { blue }
            t.def_figure('Red') { red }
            t.save_dir = 'figures_out'
        end

        def blue
            t.fill_color = Blue
            t.fill_frame
        end

        def red
            t.fill_color = Red
            t.fill_frame
        end

    end

    MyFigures.new