(use eggdoc)

(define doc
  `((eggdoc:begin
     (name "unitconv")
     (description "Conversion of units of measurement")
     (author (url "http://chicken.wiki.br/users/ivan-raikov" "Ivan Raikov"))

     (history 
      (version "1.7" "Exporting the Rate quantity")
      (version "1.6" "Exporting the IEC standard prefixes")
      (version "1.5" "Ported to Chicken 4")
      (version "1.4" "The predefined quantities have been put into unit-definitions.scm")
      (version "1.3" "Bug fix in unit-convert")
      (version "1.2" "Changed unit-convert to return a single numeric value given a single conversion argument")
      (version "1.1" "Added information units [patch by Joshua Griffith]")
      (version "1.0" "Initial release"))

     (requires)

     (usage "(require-extension unitconv)"
	    "(include \"unit-definitions\")")

     (download "unitconv.egg")

     (documentation
      
      (p "The " (tt "unitconv") " library is an implementation of unit "
	 "conversion routines based on the paper by Gordon S. Novak: " 
	 (pre "Conversion of Units of Measurement.
IEEE Trans. on Software Engineering, vol. 21, no. 8 (Aug. 1995), pp. 651-661.")
	 "(Available online at " (url "http://www.cs.utexas.edu/users/novak/units95.html") "). ")

      (p "Correctness of unit conversion is established by the technique of dimensional analysis: "
         "the source and goal units must have the same dimensions. "
         "Following Novak, this extension defines a dimension as an 8-vector of "
         "integral powers of the following base quantities: ")
 
      (pre #<<EOF
(define-base-quantity  Unity          0)
(define-base-quantity  Length         dimvals[0])
(define-base-quantity  Time           dimvals[1])
(define-base-quantity  Temperature    dimvals[2])
(define-base-quantity  Mass           dimvals[3])
(define-base-quantity  Current        dimvals[4])
(define-base-quantity  Luminosity     dimvals[5])
(define-base-quantity  Substance      dimvals[6])
(define-base-quantity  Currency       dimvals[7])
(define-base-quantity  Information    dimvals[8])
EOF
)
     (p "The unit conversion routine uses dimension integers to check that the requested unit conversion is legitimate. "
         "For example, the conversion from kilograms to meters illegal. Consequently, the dimensionality of each "
        "unit must be specified when the unit is declared. ")

      (pre #<<EOF
;; Syntax is (define-unit name quantity factor abbreviation ...)

;; define units of length
(define-unit meter     Length 1.0       m meters)
(define-unit inch      Length 0.0254    in inches)

;; define units of mass and time
(define-unit kilogram  Mass   1.0       kg kilograms)
(define-unit second    Time   1.0       s seconds)

;; define two new derived quantities: acceleration and force
(define-quantity   Acceleration  (/ Length (** Time 2)))
(define-quantity   Force         (* Mass Acceleration))

;; define a unit of force
(define-unit newton       Force (/ (* kilogram meter) (* second second)) nt newtons)

EOF
) 

    (p "Now only conversion between units of the same dimensionality is permitted: ")
    (pre #<<EOF
(unit-convert meter inch 1) ->  39.3700787401575
(unit-convert meter inch 2 3 4) ->  (78.740157480315 118.110236220472 157.48031496063)

(unit-convert meter kilogram 1)
Error: (unitconv) unit-convert : given units are of different dimensions: 
 source= #(unit meter (m meters) [Length] 1.0) ; 
 dest=  #(unit kilogram (kg kilograms) [Mass] 1.0)
EOF
)

  (subsection "Procedures and Macros"

    (procedure "unit-convert:: SRC * DEST * [VAL1 ...] -> (FACTOR1 ... )"
	       ((p "Converts the given numeric values expressed in unit " (tt "SRC") 
		   " to their equivalents in unit " (tt "DEST") ". ")
		(p "Arguments " (tt "SRC, DEST") " are records of type " (tt "unit") ". "
		   "See the definitions below for information about the units that are "
		   "defined by this extension, as well as for information about creating "
		   "new units.")))

     (procedure "unit-equal?:: UNIT1 * UNIT2 -> BOOL"    
		"Returns true if the two units have the same dimension and factor, false otherwise. ")

     (macro "(define-quantity name expr)"
       ((p "Defines a derivative quantity " (tt "NAME") ". ")
	(p (tt "EXPR") " is an S-expression with the following syntax: "
	   (pre #<<EOF
quantity-expr ::=  base-quantity
                 | derived-quantity
                 | (* quantity-expr quantity-expr)
                 | (* quantity-expr integer)
                 | (/ quantity-expr quantity-expr)
                 | (/ quantity-expr integer)
                 | (** quantity-expr integer)
EOF
)
	   " where " (br)
	   (table (tr (td (tt "base-quantity"))    (td "one of the predefined base quantities"))
		  (tr (td (tt "derived-quantity")) (td "a quantity created by " (tt "define-quantity")))
		  (tr (td (tt "**"))               (td "exponentiation operator"))))))
	   

     (macro "(define-unit name dims factor . abbrevs)"
       ((p "Defines a variable " (tt "NAME") " that holds a unit definition "
           "of a unit with the given dimension and factor. ")
        (p (tt "DIMS") " can be either one of the base quantities (see next section) "
	  " or a derivative quantity created by " (tt "define-quantity") ". ")))
	  
  )

   

  (subsection "Predefined Quantities"
    (subsubsection "Base Quantities"
      (table (tr (td (tt "Unity") "  (dimensionless)"))
	     (tr (td (tt "Length")))
	     (tr (td (tt "Time")))
	     (tr (td (tt "Temperature")))
	     (tr (td (tt "Mass")))
	     (tr (td (tt "Current")))  
	     (tr (td (tt "Luminosity")))
	     (tr (td (tt "Substance")))
	     (tr (td (tt "Currency")))
	     (tr (td (tt "Information"))))))

    (subsubsection "Derived Quantities"
      (table (tr (@ (class "heading")) (td (b "Geometry")))
	     (define-quantity   Area     (** Length 2))
	     (define-quantity   Volume   (** Length 3))
	     (tr (@ (class "heading")) (td (b "Mechanics")))
	     (define-quantity   Velocity      (/ Length Time))
	     (define-quantity   Acceleration  (/ Length (** Time 2)))
	     (define-quantity   Force         (* Mass Acceleration))
	     (define-quantity   Pressure      (/ Force Area))
	     (define-quantity   Energy        (* Force Length))
	     (define-quantity   Power         (/ Energy Time))
	     (tr (@ (class "heading")) (td (b "Electricity")))
	     (define-quantity   Charge         (* Current Time))
	     (define-quantity   Potential      (/ Energy Charge))
	     (define-quantity   Capacitance    (/ Charge Potential))
	     (define-quantity   Resistance     (/ Potential Current))
	     (define-quantity   Conductance    (/ Current Potential))
	     (define-quantity   Inductance     (/ (* Potential Time) Current))
	     (tr (@ (class "heading")) (td (b "Chemistry")))
	     (define-quantity   Concentration  (/ Substance Volume))
	     (define-quantity   Density        (/ Mass Volume))
	     (tr (@ (class "heading")) (td (b "Optics")))
	     (define-quantity    Luminance     (/ Luminosity Area))
	     (tr (@ (class "heading")) (td (b "Other")))
	     (define-quantity    Frequency     (/ Unity Time))
      ))
   )

  (subsection "Predefined Units"
      (table (table-section "SI Unit Prefixes")
	     (tr (@ (class "heading")) (td (i "Name")) (td (i "Quantity")) (td (i "Factor")) )
	     (define-unit yocto  Unity 1.0e-24)
	     (define-unit zepto  Unity 1.0e-21)
	     (define-unit atto   Unity 1.0e-18)
	     (define-unit femto  Unity 1.0e-15)
	     (define-unit pico   Unity 1.0e-12)
	     (define-unit nano   Unity 1.0e-9)
	     (define-unit micro  Unity 1.0e-6)
	     (define-unit milli  Unity 1.0e-3)
	     (define-unit centi  Unity 1.0e-2)
	     (define-unit deci   Unity 1.0e-1)
	     (define-unit deca   Unity  1.0e1)
	     (define-unit hecto  Unity  1.0e2)
	     (define-unit kilo   Unity  1.0e3)
	     (define-unit mega   Unity  1.0e6)
	     (define-unit giga   Unity  1.0e9)
	     (define-unit tera   Unity  1.0e12)
	     (define-unit peta   Unity  1.0e15)
	     (define-unit exa    Unity  1.0e18)
	     (define-unit zetta  Unity  1.0e21)
	     (define-unit yotta  Unity  1.0e24)
	     (table-section "Time Multiples")
	     (define-unit twelve Unity 12)
	     (define-unit sixty  Unity 60)
	     (table-section "Angles")
	     (define-unit radian    Unity  1.0  rad radians)
	     (define-unit degree    Unity  (/ pi 180)  deg degrees)
	     (table-section "Units of Length")
	     (define-unit meter     Length 1.0       m meters)
	     (define-unit inch      Length 0.0254    in inches)
	     (define-unit foot      Length 0.3048    ft feet)
	     (define-unit angstrom  Length 1.0e-10   ang angstroms)
	     (define-unit parsec    Length 3.083e16  parsecs)
	     (table-section "Units of Area and Volume")
	     (define-unit square-meter  Area (* meter meter) m^2 m2 meter-squared meters-squared square-meters)
	     (define-unit square-inch   Area  (* inch inch) in^2 inch-squared inches-squared square-inches)
	     (define-unit square-micron Area (* micrometer micrometer) um^2 micrometer-squared
	       micrometers-squared micron-squared microns-squared square-microns)
	     (define-unit square-millimeter Area (* millimeter millimeter) mm^2 millimeter-squared millimeters-squared
	       square-millimeters)
	     (define-unit cubic-meter   Volume  (* meter (* meter meter)) m^3 meter-cubed meters-cubed cubic-meters )
	     (define-unit liter         Volume  (* 0.001 cubic-meter) L litre liters)
	     (table-section "Units of Mass")
	     (define-unit kilogram     Mass  1.0       kg kilograms)
	     (define-unit gram         Mass  1e-3      g grams)
	     (define-unit pound        Mass  (* gram 453.59237) lb pounds)
	     (define-unit slug         Mass  (* pound 32.17405) slugs)
	     (define-unit atomic-mass-unit Mass 1.6605402e-27 amu atomic-mass-units)
	     (table-section "Units of Time")
	     (define-unit second       Time  1.0       s seconds)
	     (define-unit hour         Time  (* sixty (* sixty second)) h hrs hours)
	     (table-section "Units of Acceleration")
	     (define-unit meters-per-second-squared Acceleration (/ meter (* second second)) m/s2 m/s^2 m/sec2 m/sec^2)
	     (table-section "Units of Frequency")
	     (define-unit hertz Frequency 1.0 hz)
	     (table-section "Units of Force")
	     (define-unit newton       Force (/ (* kilogram meter) (* second second)) nt newtons)
	     (define-unit pound-force  Force (/ (* slug foot) (* second second)) lbf)
	     (table-section "Units of Power")
	     (define-unit watt         Power (/ (* kilogram meter meter)
						(* second second second))  W watts)
	     (define-unit horsepower   Power (* 550 (/ (* foot pound-force) second)) hp)
	     (table-section "Units of Energy")
	     (define-unit joule Energy  (* newton meter) J joules)
	     (define-unit electron-volt Energy  (* 1.60217733e-19 joule) ev electron-volts)
	     (define-unit kilowatt-hour Energy  (* kilo (* watt hour)) kwh kilowatt-hours)
	     (define-unit calorie       Energy  (* 4.184 joule) cal calories)
	     (define-unit erg           Energy  (* 1.0e-7 joule) ergs)
	     (define-unit british-thermal-unit Energy (* 1055.056 joule) btu btus)
	     (table-section "Units of Current")
	     (define-unit ampere  Current 1.0 A amp amps amperes)
	     (table-section "Units of Electric Charge")
	     (define-unit coulomb Charge  (* ampere second) C coulombs)
	     (table-section "Units of Electric Potential")
	     (define-unit volt Potential  (/ (* kilogram meter meter)
					     (* ampere second second second)) V volts)
	     (table-section "Units of Resistance")
	     (define-unit ohm Resistance  (/ volt ampere) ohms)
	     (table-section "Units of Capacitance")
	     (define-unit farad Capacitance  (/ coulomb volt) F farads)
	     (table-section "Units of Conductance")
	     (define-unit siemens Conductance (/ ampere volt) S mho)
	     (table-section "Units of Inductance")
	     (define-unit henry Inductance  (/ (* meter meter kilogram)
					       (* ampere ampere second second)) H)
	     (table-section "Units of Substance")
	     (define-unit mole Substance 1.0 mol moles)
	     (table-section "Units of density")
	     (define-unit rho Density (/ kilogram cubic-meter))
	     (table-section "Units of concentration")
	     (define-unit molarity Concentration (/ mole liter) M mol/L)
	     (define-unit parts-per-million Concentration (/ milligram kilogram) ppm)
	     (table-section "Units of temperature")
	     (define-unit degK       Temperature  1.0       K)
	     ))
   )
  

     (examples (pre #<<EOF

csi> (require-extension unitconv)

;; Unit conversion
csi> (unit-convert meter inch 2 3 4) 
 (78.740157480315 118.110236220472 157.48031496063)

;; Unit definition
csi> (define-unit  pascal Pressure (/ kilogram (* meter second second)) Pa)
csi> pascal
#(unit pascal (Pa) [Pressure] 1.0)

csi> (define-unit  pound-force-per-square-inch Pressure (/ pound-force (* inch inch)) psi)
csi> pound-force-per-square-inch
#(unit pound-force-per-square-inch (psi) [Pressure] 6894.75760251898)

csi> (unit-convert pound-force-per-square-inch pascal 1850)
12755301.5646601

;; Unit prefix definition
csi> (define millimeter     (make-unit-prefix  milli meter mm millimeters))

csi> (unit-convert inch millimeter 12)
304.8
EOF
))
 

     (license
"Copyright 2007-2009 Ivan Raikov.

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.

This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
General Public License for more details.

A full copy of the GPL license can be found at
<http://www.gnu.org/licenses/>.")))

(define (sexp->str x)
  (if (list? x)
      (if (null? x) ""
	  (let ((slst (map ->string x)))
	    (string-append "(" (string-intersperse 
				(cons (car slst) (cdr slst)) " ") ")")))
      x))

(if (eggdoc->html doc 
		   `( (eggdoc-style . ,(lambda (tag)
                         `("<style type=\"text/css\">" ,(eggdoc:css)
#<<EOF
<!--
TR.heading { border-bottom: solid; 
	     border-top: solid; 
	     border-width: 1px;
}
-->
EOF
"</style>")))
		      (table-section *macro* . 
			,(lambda (tag name) 
			   `(tr (@ (class "heading")) (td (b ,name)))))

		      (define-quantity *macro* . 
			,(lambda (tag name def)
			   `(tr (td (tt ,name)) (td (tt ,(sexp->str def))))))

		      (define-unit *macro* . 
			,(lambda (tag name q factor . abbrevs)
			   `(tr (td (tt ,name)) 
				(td (tt ,(sexp->str q))) 
				(td (tt ,(sexp->str factor))) 
				(td (tt ,(sexp->str abbrevs))) )))

                      ,@(eggdoc:make-stylesheet doc) ))

    (void))