[GRASS-SVN] r57773 - grass/trunk/vector/v.mapcalc
svn_grass at osgeo.org
svn_grass at osgeo.org
Fri Sep 20 20:03:10 PDT 2013
Author: hamish
Date: 2013-09-20 20:03:10 -0700 (Fri, 20 Sep 2013)
New Revision: 57773
Added:
grass/trunk/vector/v.mapcalc/v.mapcalc.html
Modified:
grass/trunk/vector/v.mapcalc/Makefile
Log:
now it builds; add help page with content from README
Modified: grass/trunk/vector/v.mapcalc/Makefile
===================================================================
--- grass/trunk/vector/v.mapcalc/Makefile 2013-09-21 02:06:30 UTC (rev 57772)
+++ grass/trunk/vector/v.mapcalc/Makefile 2013-09-21 03:03:10 UTC (rev 57773)
@@ -2,11 +2,13 @@
PGM = v.mapcalc
-LIBES = $(MATHLIB)
-DEPENDENCIES =
+LIBES = $(GISLIB) $(DLLIB)
+DEPENDENCIES = $(GISDEP)
include $(MODULE_TOPDIR)/include/Make/Module.make
default: cmd
+yylex.c: v.mapcalc.tab.h
+
.INTERMEDIATE: v.mapcalc.tab.c v.mapcalc.tab.h v.mapcalc.output
Added: grass/trunk/vector/v.mapcalc/v.mapcalc.html
===================================================================
--- grass/trunk/vector/v.mapcalc/v.mapcalc.html (rev 0)
+++ grass/trunk/vector/v.mapcalc/v.mapcalc.html 2013-09-21 03:03:10 UTC (rev 57773)
@@ -0,0 +1,268 @@
+<h2>DESCRIPTION</h2>
+
+<em>v.in.mapcalc</em> is a vector calculator program inspired by r.mapcalc.
+
+<h2>NOTES</h2>
+
+It's much more complicated to deal with vector maps than with raster
+maps. Particularly, there are several levels on which we might want to
+deal with a vector map. For this reason the design of v.mapcalc is
+that of a skeleton with plugins: A parser will interpret statements
+and call the appropriate functions it finds in dynamically loaded
+plugins.
+<p>
+The syntax should be able to deal with four different types:
+
+ - numbers
+ - points
+ - point lists
+ - maps
+<p>
+Numeric expressions should do what everybody would expect. There are
+some dozens of built in functions from the math library. Points and
+point lists are meant in the mathematical sense: A point is a set of
+two or three numbers, representing the coordinate. All points have
+three components, but the third, if missing has the value of
+0.0/0.0 (NaN). An expression will yield a 3D result if all arguments a
+3D. There is a set of basic built in operations like dot and cross
+product. Point lists are meant for polygons, lines, areas, etc. Points
+and point lists have no categories or attributes. And finally, of
+course, v.mapcalc deals with map expressions.
+<p>
+For numbers, the infix operators do the obvious. For other types, the
+parser will translate them to function calls with predefined
+names. Some samples are set and can be replaced by something useful.
+<p>
+The plugins are designed to be as simple as possible. There is one
+example which actually doesn't do anything but shows how it can be
+called. Such a plugin needs three global functions: One which can be
+called to find out the name the user must type to use the function,
+one which returns a string denoting the return type and the type and
+number of arguments, and finally the function itself.
+<p>
+There are two more types which are somewhat special: One is type
+`argument' which can be any of the basic types. The parser will accept
+anything to be the argument to a function call, but the mechanism to
+actually call that function will check if the types match the
+prototype. The second special type `any' is sort of a backdoor: If
+something new comes up, it can be treated as type any, and it will be
+responsibility of the plugin to verify that it's the correct type. One
+case where the any-type can be useful is for SQL statement-pieces or
+other constructs when dealing with attributes, which can be literally
+of "any" type.
+<p>
+There is one problem with this approach within v.mapcalc, which is
+calling a function with a variable list of arguments. This is a bit
+complicated, and before thinking of easy solutions, I need to
+recommend reading the code. Just before calling it, v.mapcalc has a
+pointer to that functions and a linked list of structures which hold
+the argument types and values. It would be nice to be able to
+construct such a call argument by argument, but there is no portable
+way to do so: First assembly would be needed, and second, the way a
+stack frame is built for a particular compiler/architecture can vary.
+The solution is to maintain a list of typedef'd prototypes and call
+them in a switch. This means, if someone needs a new function and
+writes a plugin, either he finds a typedef which matches this
+prototype, or he needs to add the typedef and a case in the switch.
+<p>
+It makes only limited sense to mix arguments of different types: three
+at the power of map-A doesn't seem to be useful. So, the basic
+strategy is accept expressions only of the same type, while mixing
+types is always possible within the arguments to a function call.
+<p>
+There is a file listing some example expressions. I hope that it is
+what one could expect. Adding a few plugins should allow for very
+complex expressions and operations.
+
+
+<h2>EXAMPLES</h2>
+
+This is an empty statement, which is legal
+<div class="code"><pre>
+ ;
+</pre></div>
+
+<p>
+Some built in constants:
+<div class="code"><pre>
+ 12;
+ e;
+ pi;
+ pnt_o;
+ pnt_i;
+ pnt_j;
+ pnt_k;
+ rivers;
+</pre></div>
+
+<p>
+The last one isn't really a constant, as it depends on what if found
+at startup, but it behaves just the like.
+<div class="code"><pre>
+ a;
+</pre></div>
+
+<p>
+This gives an error. "a", which is (not yet) defined, is handled as a
+string. There is no operation associated, so this gives a parse error.
+<p>
+Next some simple assignments. Also here, the name of the variable is
+initially not more than a string, but after performing the assignment,
+they take the type of the expressionL:
+<div class="code"><pre>
+ num = 10.3;
+ pnt = (0,0);
+ map = rivers;
+ any = mkstring (hallo);
+</pre></div>
+
+<p>
+The last is only a backdoor for cases when exceptional things are
+needed. The function mkstring is a sample implementation of type
+ANY. For now, only one word could be passed, but when flex is being
+used a quoted string might contain just anything.
+<p>
+Next, I overwrite these variables. This is somewhat tricky. If you say
+"map = rivers", what should happen? In theory, we should actually
+duplicate this map, which could imply gigabytes on disk. This is not
+done, but if the map is changed, it must not change the former
+`value'. I hope it's doing now, what everybody would expect (including
+to free eventually the allocated memory).
+<div class="code"><pre>
+ num = 3.1;
+ pnt = (1,1);
+ map = cities;
+ any = mkstring (hello);
+</pre></div>
+
+<p>
+The pure numeric operations aren't new, beside that I'm trying to
+catch illegal operations:
+<div class="code"><pre>
+ sqrt(e);
+ num = cos (pi/4);
+ num = -num + 3 * num - sqrt (num^2);
+ 3.3 + 4.4;
+ 2.2 - 1.1;
+ 5 * 7;
+ 21 / 0;
+ 21 / 2;
+ -21 / 7;
+ -6.6 ^ 1.2;
+ 6.6 ^ 1.2;
+ 12.5 % 3.6;
+ 2 * (3.1 + 0.9);
+</pre></div>
+
+<p>
+Next are points. Note that 2D and 3D are dealt with identically; in
+case of 2D, the z-value is 0.0/0.0 (NaN, "Not a Number"). This should
+be pretty portable. Generally, if at least one point is 2D, the result
+of a point operation will be 2D even if 3D points are involved too,
+ignoring the third dimension. I've defined some infix operations a bit
+arbitrarily. Of course, this could be changed. The double () in case
+of a single function argument are surely ugly, but not avoidable.
+<div class="code"><pre>
+ origin2d = (0,0);
+ p1 = (1,1);
+ p2 = p1;
+ p2 = v_copy (p1);
+ v_add ((1,0), (0,1));
+ (1,0) + (0,1);
+ v_sub ((1,1), (0,1));
+ (1,1) - (0,1);
+ v_abs ((-2, -1));
+ v_neg ((2, 1));
+ -(2,1);
+ v_mul ((2,4), 3.3);
+ (2,4) * 3.3;
+ 3.3 * (2,4);
+ v_div ((6.6, 13.2), 3.3);
+ (6.6, 13.2) / 3.3;
+ v_unit ((12, 8));
+ v_cross ((1,2), (4,5));
+ v_cross ((1,2,3), (4,5,6));
+ (1,2,3) ^ (4,5,6);
+ v_val ((3,3));
+ v_dot ((1,2), (3,4));
+ (1,2) % (3,4);
+ v_dot ((1,2,3), (4,5,6));
+ (1,2,3) % (4,5,6);
+ v_area ((1,2,3), (4,5,6));
+ v_eq ((1,2), (1, 2));
+ v_eq ((1,2), (1.0001, 2.0001));
+ epsilon = (1e-3, 1e-3);
+ v_eq_epsilon ((1,2), (1.0001, 2.0001), epsilon);
+ v_isortho ((0,1), (1,0));
+ v_ispara ((0, 1), (0, -1));
+ v_isacute ((0, 1), (0, 0.5));
+ 3 * (pnt + (2,2));
+</pre></div>
+
+<p>
+This is planned, but doesn't work yet:
+<div class="code"><pre>
+ line = ((1,1), (2,1));
+ triangle = (line, (1.5, 2));
+</pre></div>
+
+<p>
+And finally the map operations, which also aren't new, beside some
+internal details (freeing memory, not duplicating, etc.). I think that
+there is no map-operation which makes sense if it is not assigned to a
+variable. So all map expressions need to follow a variable and an
+equal sign. The very first expression, hence, will give an error:
+<div class="code"><pre>
+ rivers + cities;
+ map = rivers;
+ map;
+ map = rivers + cities;
+ map = testmap (rivers);
+ map = test2map (rivers, cities);
+ map = dltest (rivers, cities);
+</pre></div>
+
+
+<h2>TODO</h2>
+
+- The lexical scanner. At this point, there is a very simple and
+ limited scanner. My plan was to provide 4 methods of input:
+ + from the command line
+ + from stdin, interactively, using GNU readline and history
+ + from stdin by IO redirection like in "script | v.mapcalc"
+ + from a file, like in "v.mapcalc -i statementfile"
+ Of course, this should be done with Flex, with the input selection
+ as needed for all methods, as well as support for Bison to indicate
+ the position of a parse error.
+- There should be several built in commands allowing to:
+ + include a file with statements
+ + document the meaning of a variable or function
+ + attaching documentation to a variable or function
+ + saving certain things in a readable script like documentation or
+ constant values.
+ + a command to terminate the program (right now, only with Ctrl-D)
+- There is not yet any support for loops and conditionals. These do
+ not seem to be of much use with maps, but can prove powerful on
+ points and point lists.
+- There are certain operations which need to be performed always, like
+ opening a map. For now, they need to be done in the plugin, but
+ should definitively move to v.mapcalc.
+- Point lists are not working yet, though much of the basic
+ infrastructure is already done.
+- There seems to be a bug in memory management which can cause the
+ program to crash. Probably there are many more than that.
+
+
+<h2>SEE ALSO</h2>
+
+<em>
+ <a href="r.mapcalc.html">r.mapcalc</a>
+</em>
+
+
+<h2>AUTHOR</h2>
+
+Christoph Simon <ciccio at kiosknet com.br>
+
+<p>
+<i>Last changed: $Date$</i>
Property changes on: grass/trunk/vector/v.mapcalc/v.mapcalc.html
___________________________________________________________________
Added: svn:mime-type
+ text/html
Added: svn:keywords
+ Author Date Id
Added: svn:eol-style
+ native
More information about the grass-commit
mailing list