X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdgraph_rpn.src;fp=doc%2Frrdgraph_rpn.src;h=3278f84179cad1740956f1a8bf53682d9d0ebefc;hp=0000000000000000000000000000000000000000;hb=b7c278771851b0dfad0daf1c817fbc93316ef96e;hpb=ffbbe12c9849a0750836c30fdb7306e83107dec4

diff --git a/doc/rrdgraph_rpn.src b/doc/rrdgraph_rpn.src
new file mode 100644
index 0000000..3278f84
--- /dev/null
+++ b/doc/rrdgraph_rpn.src
@@ -0,0 +1,219 @@
+=include name
+
+=head1 SYNOPSYS
+
+I<E<lt>RPN expressionE<gt>> := 
+I<E<lt>vnameE<gt>>|I<E<lt>operatorE<gt>>|I<E<lt>valueE<gt>>
+[ , I<E<lt>RPN expressionE<gt>>]
+
+=head1 DESCRIPTION
+
+If you have ever used a traditional HP calculator you already know
+B<RPN>. The idea behind B<RPN> is that you have a stack and push
+your data onto this stack. Whenever you execute an operation, it
+takes as many elements from the stack as needed. Pushing is done
+implicit so whenever you specify a number or a variable, it gets
+pushed automatically.
+
+At the end of the calculation there should be one and exactly one
+value left on the stack.  This is the outcome of the function and
+this is what is put into the I<vname>.  For B<CDEF> instructions,
+the stack is processed for each data point on the graph. B<VDEF>
+instructions work on an entire data set in one run.
+
+Example: C<CDEF:mydatabits=mydata,8,*>
+
+This means:  push variable I<mydata>, push the number 8, execute
+the operator I<+>. The operator needs two elements and uses those
+to return one value.  This value is then stored in I<mydatabits>.
+As you may have guessed, this instruction means nothing more than
+I<mydatabits = mydata * 8>.  The real power of B<RPN> lies in the
+fact that it is always clear in which order to process the input.
+For expressions like C<a = b + 3 * 5> you need to multiply 3 with
+5 first before you add I<b> to get I<a>. However, with parentheses
+you could change this order: C<a = (b + 3) * 5>. In B<RPN>, you
+would do C<a = b, 3, +, 5, *> and need no parentheses.
+
+=head1 OPERATORS
+
+=over 4
+
+=item Boolean operators
+
+B<LT, LE, GT, GE, EQ, NE>
+
+I<Note: NE is not yet implemented>
+
+Pop two elements from the stack, compare them for the selected condition
+and return 1 for true or 0 for false. Comparing an I<unknown> or an
+I<infinite> value will always result in 0 (false).
+
+B<UN, ISINF>
+
+I<Note: ISINF is not yet implemented>
+
+Pop one element from the stack, compare this to I<unknown> respectively
+to I<positive or negative infinity>. Returns 1 for true or 0 for false.
+
+B<IF>
+
+Pops three elements from the stack.  If the last element is 0 (false),
+the first value is pushed back onto the stack, otherwise the second
+popped value is pushed back. This does, indeed, mean that any value
+other than 0 is considered true.
+I<Note: Should this change? It should IMHO as all the other functions
+would return unknown if A,B or C were unknown>
+
+Example: C<A,B,C,IF> should be read as C<if (A) then (B) else (C)>
+
+Z<>
+
+=item Comparing values
+
+B<MIN, MAX> 
+
+Pops two elements from the stack and returns the lesser or larger.
+The two numbers shouldn't be I<infinite> or I<unknown>, if they are
+that value is pushed back onto the stack as the result.
+
+B<LIMIT>
+
+Pops two elements from the stack and uses them to define a range.
+Then it pops another element and if it falls inside the range, it
+is pushed back. If not, an I<unknown> is pushed.
+
+The range defined includes the two boundaries (so: a number equal
+to one of the boundaries will be pushed back). If any of the three
+numbers involved is either I<unknown> or I<infinite> this function
+will always return an I<unknown>
+
+Example: C<CDEF:a=alpha,0,100,LIMIT> will return I<unknown> if
+alpha is lower than 0 or if it is higher than 100.
+
+Z<>
+
+=item Arithmetics
+
+B<+, -, *, /, %>
+
+Add, subtract, multiply, divide, modulo
+
+B<SIN, COS, LOG, EXP>
+
+Sine, cosine (input in radians), log, exp (natural logarithm)
+
+B<FLOOR, CEIL>
+
+Round down,up to the nearest integer
+
+Z<>
+
+=item Special values
+
+B<UNKN>
+
+Pushes an unknown value on the stack
+
+B<INF, NEGINF>
+
+Pushes a positive or negative infinite value on the stack. When
+such a value is graphed, it appears at the top or bottom of the
+graph, no matter what the actual value on the y-axis is.
+
+B<PREV>
+
+Pushes an I<unknown> value if this is the first value of a data
+set or otherwise the result of this B<CDEF> at the previous time
+step. This allows you to do calculations across the data.  This
+function cannot be used in B<VDEF> instructions.
+
+Z<>
+
+=item Time
+
+Time inside RRDtool is measured in seconds since the epoch. This
+epoch is defined to be S<C<Thu Jan  1 00:00:00 UTC 1970>>.
+
+Z<>
+
+=over 4
+
+=item NOW
+
+Pushes the current time on the stack.
+
+Z<>
+
+=item TIME
+
+Pushes the time the currently processed value was taken onto the stack.
+
+Z<>
+
+=item LTIME
+
+Takes the time as defined by B<TIME>, applies the time zone offset
+valid at that time including daylight saving time if your OS supports
+it, and pushes the result on the stack.  There is an elaborate example
+in the examples section on how to use this.
+
+=back
+
+For B<VDEF> operations, B<TIME> and B<LTIME> have a different meaning
+I<not yet implemented>.  As the B<VDEF> statement does not work per
+value but rather on a complete time series, there is no such thing as
+the currently processed value.  However, if you have used an operator
+that returned a time component and would like to have this available
+in the value component in stead (so you can use it as a number), you
+can use B<TIME> or B<LTIME> for that.
+
+Z<>
+
+=item Processing the stack directly
+
+B<DUP, POP, EXC>
+
+Duplicate the top element, remove the top element, exchange the two
+top elements.
+
+Z<>
+
+=item Selecting characteristics
+
+These operators work only on B<VDEF> statements.
+I<We can make most of them work at DEF and CDEF statements. If we do
+so, we have a moving (not rolling!) average, max,min etcetera>
+
+Z<>
+
+=over 4
+
+=item MAXIMUM, MINIMUM, AVERAGE
+
+Return the corresponding value
+
+Z<>
+
+=item LAST, FIRST
+
+Return the last,first value including its time 
+
+Z<>
+
+=item PERCENTILE
+
+Should follow a B<DEF> or B<CDEF> I<vname>. This I<vname> is popped,
+another number is popped which is a certain percentage (0..100). The
+data set is then sorted and the value returned is chosen such that
+I<percentage> percent of the values is lower or equal than the result.
+I<Unknown> values are considered lower than any finite number for this
+purpose so if this operator returns an I<unknown> you have quite a lot
+of them in your data...
+
+Example: C<VDEF:perc95=95,mydata,PERCENTILE>
+
+=back
+
+=back
+
+=include see_also