(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.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))