Join GitHub today
GitHub is home to over 20 million developers working together to host and review code, manage projects, and build software together.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
NAME Text::LookUpTable - Perl5 module for text based look up table operations SYNOPSIS $tbl = Text::LookUpTable->load_file('my_table.tbl'); $tbl = Text::LookUpTable->load($str_tbl); $tbl = Text::LookUpTable->build($x_size, $y_size, $x_title, $y_title); print $tbl; $str_tbl = "$tbl"; $tbl->save_file(); $tbl->save_file('my_table.tbl'); $val = $tbl->get($x, $y); $tbl->set($x, $y, $val); @diff_coords = $tbl->diff($tbl2); $diffp = $tbl->diff($tbl2, 1); # true/false no coordinates @xdiffs = $tb1->diff_x_coords($tb2); @ydiffs = $tb1->diff_y_coords($tb2); @x_coords = $tbl->get_x_coords(); @y_coords = $tbl->get_y_coords(); $res = $tbl->set_x_coords(@x_coords); $res = $tbl->set_y_coords(@y_coords); $str_plot = $tbl->as_plot('R'); $str_plot = $tbl->as_plot('Maxima'); print FILE $str_plot; $tbl_copy = $tbl->copy(); DESCRIPTION Text::LookUpTable provides operations for creating, storing, displaying, plotting, loading, and querying a *look up table* structure. The format of the stored structure is designed to be visually easy to understand so that it can be easily edited using a text editor. The authors inteded use of this library is to allow a user to edit a text file representation of a look up table which can then be loaded in to an embedded controller such as MegaSquirt [http://www.msextra.com]. Additional code would be needed to convert this generic structure to whatever application specific format is required. What is a *look up table* and how is it different than a *table*? A *look up table* is commonly used in embedded controllers to avoid the use of costly floating pointing operations by looking up a value based on the input coordiantes. A function with two inputs (f(x, y)) which would use floating point operations can be represented (with some loss in precsion) as a table. In contrast a *table* (or spreadsheet) has any number of columns/rows. The columns can be of different types. And a table does not try to represent any sort of function, it just stores data. STRING FORMAT The format of the look up table when stored to a string or file should look like the example below. rpm      14.0 15.5 16.4 17.9 map  13.0 14.5 15.3 16.8  12.0 13.5 14.2 15.7 The x (across top) and y (left column) coordinates have their values enclosed in square brackets. All values must be present. And the titles can only span one line. There can be any number of lines and spaces as long as the values can be discerned. When saving and restoring a table the original spacing will not be preserved. The x values start at offset 0 at the left and increase towards the right. The y values start at offset 0 at the bottom and increase upward. OPERATIONS Text::LookUpTable->load($string); Returns: a new table object on success, FALSE on error Creates a new look up table object by parsing the given string. See the section *STRING FORMAT* for details on format it expects. If you want to load a table from a *file* see *load_file*. Text::LookUpTable->load_file($file) Returns: new object on success, FALSE on error Works like *load* but obtains the text from the $file first. Stores the name of file so that save_file can be used without having to specify the file again. Text::LookUpTable->build($x_size, $y_size, $x_title, $y_title) Returns: new object on success, FALSE on error Creates a blank object with all values initialized to zero and dimensions of $x_size and $y_size. Text::LookUpTable->copy($obj) Returns: new object on success, FALSE on error Creates a new object as a copy of the given object. $tbl->as_string(); Returns string on success, FALSE on error. Convert the object to a string representation. This operation is used to overload the string operation so the shorthand form can be used. print $tbl; # print the object as a string $to_save = "$tbl"; # get the string format to be saved The long hand form $tbl->as_string(); should not normally be needed. $tbl->save_file($file); Returns TRUE on success, FALSE on error Optional argument $file, can specify the file to save to. If ommitted it will save to the last file that was used. If no last file is stored it will produce an error. $tbl->get_*_coords(); Returns list of all x/y coordinates on success, FALSE on error Offset 0 for the X coordinates start at the LEFT of the displayed table and increases RIGHTWARD. Offset 0 for the Y coordinates start at the BOTTOM of the displayed table and increases UPWARD. @xs = $tbl->get_x_coords(); @ys = $tbl->get_y_coords(); $tbl->set_*_coords(@new_coords); Returns TRUE on success, FALSE on error Assigns the x/y coordinates to the values given in the list. The coordinates must be in ascending order so that lookup_points, etc will work correctly. $res = $tbl->set_x_coords(@new_x_coords); $res = $tbl->set_y_coords(@new_y_coords); $tbl->set($x, $y, $val); Returns TRUE on success OR FALSE on error Set the value to $val at the given $x and $y coordinate offset. $tbl->get($x, $y); Returns $value on success, FALSE on error Get the value at the given horizontal ($x) and vertical ($y) offset. $tbl->lookup_points($val_x, $val_y, $range); Returns @points (see below) on success, FALSE on error Lookup the points for the given values. The $range argument defines how far from the nearest point in the x and y direction the resulting set of points should include. Unlike offsets (see get()) which correspond to one point, a lookup based on values may correspond to multiple points of varying degrees (closer to some points than others). Suppose, for example, we are given the following map rpm       14.0 15.5 16.4 17.9 21.9 map  13.0 14.5 15.3 16.8 21.9  12.0 13.5 14.2 15.7 20.5  12.0 13.5 14.2 15.7 20.1  12.0 13.5 14.2 15.7 18.2 A lookup of the x value of 2010 and a y value of 85 (notice the values do not correspond exactly) and a range of 1 would select the points shown below (show with an X). @points = $tbl->lookup_points(2010, 85, 1); rpm       14.0 15.5 16.4 17.9 21.9 map  13.0 X X X 21.9  12.0 X X X 20.5  12.0 X X X 20.1  12.0 13.5 14.2 15.7 18.2 The set of points returned would be (in no particular order) ([1, 1], [1, 2], [1, 3], [2, 1], [2, 2], [2, 3], ...) And this set of points could then be used to retrieve and/or assign the range of values. $tb1->diff($tb2, $break); Returns TRUE if different, FALSE otherwise. If $break is FALSE it returns a list of positions that are different. Determines whether the VALUES two tables are different. Does not check if the coordinates or the titles are different. If $break is FALSE return a complete list of coordinates that are different. If $break is TRUE it breaks out and returns as soon it is found that they are different for a slight performance improvement. $tb1->diff_*_coords($tb2) Returns list of differences on success, FALSE on error @xdiffs = $tb1->diff_x_coords($tb2); @ydiffs = $tb1->diff_y_coords($tb2); $tbl->as_plot('plot type', [type specific args ...] ); Returns: string on success, FALSE on error Convert the table to a representation suitable for plotting. The string may need to be output to a file depending on how the plotting program is called. See below for the various plot types. R [www.r-project.org] The string can be output to a file and then the file can be sourced to produce a plot. It depends upon the rgl library [http://cran.r-project.org/web/packages/rgl/index.html]. $tbl->as_plot('R'); shell$ ./a.out > file.R shell$ R > source('file.R') (plot displayed) Maxima [maxima.sourceforge.net] Example usage using lutasplot.pl utility (in bin directory). shell$ lutasplot.pl veTable1 Maxima > veTable1.maxima shell$ maxima (%i1) batch("veTable1.maxima"); (..., plot output, etc) PREREQUISITES Module Version ------ ------- Text::Aligner 0.03 File::Slurp 9999.13 The version numbers given have been tested and shown to work but other versions may work as well. VERSION This document refers to Text::LookUpTable version 0.07. REFERENCES  MegaSquirt Engine Management System http://www.msextra.com  R Project http://www.r-project.org  rgl: 3D visualization device system (OpenGL) http://cran.r-project.org/web/packages/rgl/index.html  Gnuplot http://www.gnuplot.info  Maxima http://maxima.sourceforge.net AUTHOR Jeremiah Mahler <email@example.com> CPAN ID: JERI https://plus.google.com/+JeremiahMahler/about COPYRIGHT Copyright (c) 2014, Jeremiah Mahler. All Rights Reserved. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.