FormatR::Format (Class)

In: format.rb
Parent: Object
Formatter ScientificNotationFormatter CenterFormatter RightFormatter LeftFormatter NumberFormatter Array FormatHolder Exception FormatException Format FormatReader FormatEntry FormatR Module: FormatR

The class that exports the functionality that a user is interested in.


io  [RW]  Set the IO that the format will be printed to, from stdout to a file for example.

Public Class methods

Create a new format with the given top, bottom, and middle formats. One argument will default to a top while two will give you a top and a middle. If you want a bottom and no top you’ll need to pass an empty format in as the first argument or a nil. The output defaults to standard out but can be changed with the method.

The format is a string in the style of a perl format or an array of strings each of which is a line of a perl format. The passed in format contains multiple lines, picture lines and argument lines. A picture line can contain any text but if it contains an at field (@ followed by any number of <,>,| or a group of #’s of the format #*.#* or #*) it must be followed by an argument line. The arguments in the argument line are inserted in place of the at fields in the picture line. Perl documentation for formats can be found here: An example of a format is

 format = <<DOT
 Name: @<<<       @<<<<<
       first_name last_name

This line specifies that when requested one line should be printed and that it will say "Name: #{first_name} #{last_name}\n" but that if either of those variables is longer than the length its format the result will be truncated to the length of the format.

An at field specified as @<* specifies that the variable should be left justified within the space allocated. @>* is right justified, and @| is centered. #’s are used to print numbers and can be used to set the number of digits after the decimal point. However the whole number portion of an argument will always be printed in its entirety even if it takes space set for the fractional portion or even more space. If the fractional portion is not long enough to fill the described space it will be padded with 0s.

Public Instance methods

If you’re writing to the file handle in another way than by calling printFormat you can keep the pagination working using this call to correctly keep track of lines.

When you don’t want anymore on this page just fill it with blank lines and print the bottom if it’s there, print a ^L also. This is good if you want to finish off the page but print more later to the same file.

When you don’t want anymore on this page just fill it with blank lines and print the bottom if it’s there. Don‘t print a ^L at the end. This is good if this will be the last page.

return an Array of picture line FormatHolder s

How big is the format? May be useful if you want to try a bottom with a variable length format

Return how many times the top has been printed. You can use this to number pages. An empty top can be used if you need the page number but don’t want to print any other header. This is a somewhat interesting function as the bottom is only printed when a page is finished or a top is needed. If this is the case we’ll pretend the page number is one h

Print out the specified format. You need to pass in a Binding object for the variables that will be used in the format. This is usually just a call to Kernel.binding. The next argument gives a file handler to print to. This is useful so that a top or bottom’s output get written to the same place as the main format is going even if their formats have a different io when they’re not attached.

print the format given that the binding is actually a binding.

print the format given that the binding is a hash of values. This method will not call eval at all.

Sets the variable that says how many lines may be printed to the maximum for the page which can be set using setPageLength (anInt). Defaults to 60.

Set a format to print at the end of a page. This is tricky and you should be careful using it. It currently has problems on short pages (at least). In order for a bottom to show up you need to finish off a page. This means that formats less than a page will need to be finished off with a call to one of the finishPageWith[out]FF methods.

If you want to tell the system how many lines are left.

Sets the number of lines on a page. If you don’t want page breaks set this to some large number that you hope you won’t offset or liberally use resetPage. The default is 60.

If you want something to show up before the regular text of a format you can specify it here. It will be printed once above the format it is being set within. You can pass in either a format or the specification of a format and it will make one for you.

print out all the values we’re holding for pictures useful for debugging

if one format sets the @use_hash value everyone else will need to know too