source: project/wiki/eggref/5/slib-charplot @ 38382

[[tags: egg]]

== slib-charplot

[[toc:]]


=== Description

A port of the [[http://people.csail.mit.edu/jaffer/SLIB|SLIB]] character
plotting library. For SLIB documentation see
[[http://people.csail.mit.edu/jaffer/slib/Character-Plotting.html#Character-Plotting|charplot]].

=== Documentation

'''Note''' that the SLIB documentation describes {{charplot:dimensions}}.
This, and other plot defining variables, are ''not'' exported here. Rather
{{parameter}}s are provided.

===== Usage

<enscript language=scheme>
(import slib-charplot)
</enscript>

===== plot-dimensions

<procedure>(plot-dimensions [DIMS]) -> (or boolean (list exact-integer exact-integer))</procedure>

A list of the maximum height (number of lines) and maximum width (number of
columns) for the graph, its scales, and labels.

The default value uses the output-port-height and output-port-width of
current-output-port at plot time.

; {{DIMS}} : {{(or #f (list exact-integer exact-integer))}} ; (Height-rows Width-columns), default {{#f}}.

The left-margin effects the width consumed. The effective minimum dimensions
are {{(4 (+ 5 (plot-left-margin)))}}.

Use this {{parameter}} instead of {{charplot:dimensions}}.

===== plot-left-margin

<procedure>(plot-left-margin [WID]) -> exact-integer</procedure>

; {{WID}} : {{(or #f exact-integer)}} ; Width-columns, initial {{12}}, with default {{2}}.

{{2}} is the the minimum value.

Use this {{parameter}} instead of {{charplot:left-margin}}.

===== xborder-char
===== yborder-char
===== xaxis-char
===== yaxis-char
===== xtick-char
===== bar-char

<procedure>(xborder-char [CHAR]) -> char</procedure>
<procedure>(yborder-char [CHAR]) -> char</procedure>
<procedure>(xaxis-char [CHAR]) -> char</procedure>
<procedure>(yaxis-char [CHAR]) -> char</procedure>
<procedure>(xtick-char [CHAR]) -> char</procedure>
<procedure>(bar-char [CHAR]) -> char</procedure>

Use these {{parameter}}s instead of {{char:xborder}}, {{char:yborder}}, {{char:xaxis}},
{{char:yaxis}}, {{char:xtick}} & {{char:bar}}.

===== curves-chars

<procedure>(curves-chars [CHARS]) -> exact-integer</procedure>

; {{CHARS}} : {{(or #f string)}} ; characters to use for the plot curve, {{#f}} uses the default set.

Use this {{parameter}} instead of {{char:curves}}.

===== plot

<procedure>(plot COORDS X-LABEL Y-LABEL [HISTOGRAM?])</procedure>

{{COORDS}} is an array, list or vector of coordinates, lists of x and y coordinates.
{{X-LABEL}} and {{Y-LABEL}} are strings with which to label the x and y axes.

; {{COORDS}} : {{(or array list vector)}} ; coordinate data elements
; {{X-LABEL}} : {{string}} ; x axis label.
; {{Y-LABEL}} : {{string}} ; y axis label.
; {{HISTOGRAM?}} : {{boolean}} ; line or filled graph.

The elements of a {{list}} are of the form {{(X Y1 ... Yn)}}, where {{(< 0
n)}}. Other accepted forms are: {{(X . Y)}} & {{(X (Y1 ... Yn))}}, which are
interpreted as {{(X Y)}} & {{(X Y1 ... Yn)}}, respectively.

The elements of a 1-dim {{array}} or {{vector}} are of type {{Y}} or {{(Y1 ...
Yn))}}. The missing {{X}} value is generated from {{[0 .. c-1]}}, where {{c}}
is the cardinality of the {{array}} or {{vector}}. The generated data is then
{{(X Y ...)}}.

The elements of a 2-dim {{array}} are interpreted as {{(X Y ...)}}.

The following {{COORDS}} produce the same plot:
* {{(list->array 2 '#() '((0 12 21) (1 21 12)))}}
* {{#((12 21) (21 12))}}
* {{((0 12 21) (1 21 12))}}

<procedure>(plot FUNC X1 X2 [NPTS])</procedure>

Plots the function of the single-argument {{FUNC}} over the range {{X1}} to
{{X2}}. If the optional integer argument {{NPTS}} is supplied, it specifies
the number of points to evaluate func at.

; {{FUNC}}  : {{(number -> float)}} ; function to plot.
; {{X1}} : {{number}} ; plot range start.
; {{X2}} : {{number}} ; plot range end.
; {{NPTS}} : {{exact-integer}} ; number of points to evaluate {{FUNC}}, default {{64}}.

===== histograph

<procedure>(histograph DATA LABEL)</procedure>

Creates and displays a histogram of the numerical values contained in vector
or list {{DATA}}. {{LABEL}} is a string.

; {{DATA}} : {{(or list vector)}} ; elements are {{number}}.
; {{LABEL}} : {{string}} ; plot label.


=== Author

Aubrey Jaffer


=== Maintainer

[[/users/kon-lovett|Kon Lovett]]


=== Requirements

[[srfi-63]]


=== Version history

; 1.0.3 : {{plot}} accepts a {{SRFI-63}} {{array}}.
; 1.0.0 : C5 release.


=== License

Copyright (C) 1992, 1993, 2001, 2003 Aubrey Jaffer

Permission to copy this software, to modify it, to redistribute it,
to distribute modified versions, and to use it for any purpose is
granted, subject to the following restrictions and understandings.

1.  Any copy made of this software must include this copyright notice
in full.

2.  I have made no warranty or representation that the operation of
this software will be error-free, and I am under no obligation to
provide any services, by way of maintenance, update, or otherwise.

3.  In conjunction with products arising from the use of this
material, there shall be no use of my name in any advertising,
promotional, or sales literature without prior written consent in
each case.