diff --git a/src/pkgdefaults.jl b/src/pkgdefaults.jl index 56a1dbfd..09a38d47 100644 --- a/src/pkgdefaults.jl +++ b/src/pkgdefaults.jl @@ -2,68 +2,110 @@ # The dimension symbols are generated by tab completion: \bfL is ๐‹, etc. # At the expense of easy typing, this gives a visual cue to distinguish # dimensions from units, and also helps prevent common namespace collisions. -@dimension ๐‹ "๐‹" Length -@dimension ๐Œ "๐Œ" Mass -@dimension ๐“ "๐“" Time -@dimension ๐ˆ "๐ˆ" Current -@dimension ๐šฏ "๐šฏ" Temperature # This one is \bfTheta -@dimension ๐‰ "๐‰" Luminosity -@dimension ๐ "๐" Amount +" Unitful.๐‹ +\nA dimension representing length." +@dimension ๐‹ "๐‹" Length true +" Unitful.๐Œ +\nA dimension representing mass." +@dimension ๐Œ "๐Œ" Mass true +" Unitful.๐“ +\nA dimension representing time." +@dimension ๐“ "๐“" Time true +" Unitful.๐ˆ +\nA dimension representing electric current." +@dimension ๐ˆ "๐ˆ" Current true +" Unitful.๐šฏ +\nA dimension representing thermodynamic temperature." +@dimension ๐šฏ "๐šฏ" Temperature true # This one is \bfTheta +" Unitful.๐‰ +\nA dimension representing luminous intensity." +@dimension ๐‰ "๐‰" Luminosity true +" Unitful.๐ +\nA dimension representing amount of substance." +@dimension ๐ "๐" Amount true const RelativeScaleTemperature = Quantity{T, ๐šฏ, <:AffineUnits} where T const AbsoluteScaleTemperature = Quantity{T, ๐šฏ, <:ScalarUnits} where T # Define derived dimensions. -@derived_dimension Area ๐‹^2 -@derived_dimension Volume ๐‹^3 -@derived_dimension Density ๐Œ/๐‹^3 -@derived_dimension Frequency inv(๐“) -@derived_dimension Velocity ๐‹/๐“ -@derived_dimension Acceleration ๐‹/๐“^2 -@derived_dimension Force ๐Œ*๐‹/๐“^2 -@derived_dimension Pressure ๐Œ*๐‹^-1*๐“^-2 -@derived_dimension Energy ๐Œ*๐‹^2/๐“^2 -@derived_dimension Momentum ๐Œ*๐‹/๐“ -@derived_dimension Power ๐‹^2*๐Œ*๐“^-3 -@derived_dimension Charge ๐ˆ*๐“ -@derived_dimension Voltage ๐ˆ^-1*๐‹^2*๐Œ*๐“^-3 -@derived_dimension ElectricalResistance ๐ˆ^-2*๐‹^2*๐Œ*๐“^-3 -@derived_dimension ElectricalResistivity ๐ˆ^-2*๐‹^3*๐Œ*๐“^-3 -@derived_dimension ElectricalConductance ๐ˆ^2*๐‹^-2*๐Œ^-1*๐“^3 -@derived_dimension ElectricalConductivity ๐ˆ^2*๐‹^-3*๐Œ^-1*๐“^3 -@derived_dimension Capacitance ๐ˆ^2*๐‹^-2*๐Œ^-1*๐“^4 -@derived_dimension Inductance ๐ˆ^-2*๐‹^2*๐Œ*๐“^-2 -@derived_dimension MagneticFlux ๐ˆ^-1*๐‹^2*๐Œ*๐“^-2 -@derived_dimension DField ๐ˆ*๐“/๐‹^2 -@derived_dimension EField ๐‹*๐Œ*๐“^-3*๐ˆ^-1 -@derived_dimension HField ๐ˆ/๐‹ -@derived_dimension BField ๐ˆ^-1*๐Œ*๐“^-2 -@derived_dimension Action ๐‹^2*๐Œ*๐“^-1 -@derived_dimension DynamicViscosity ๐Œ*๐‹^-1*๐“^-1 -@derived_dimension KinematicViscosity ๐‹^2*๐“^-1 -@derived_dimension Wavenumber inv(๐‹) -@derived_dimension ElectricDipoleMoment ๐‹*๐“*๐ˆ -@derived_dimension ElectricQuadrupoleMoment ๐‹^2*๐“*๐ˆ -@derived_dimension MagneticDipoleMoment ๐‹^2*๐ˆ -@derived_dimension Molarity ๐/๐‹^3 -@derived_dimension Molality ๐/๐Œ -@derived_dimension MassFlow ๐Œ/๐“ -@derived_dimension MolarFlow ๐/๐“ -@derived_dimension VolumeFlow ๐‹^3/๐“ +@derived_dimension Area ๐‹^2 true +@derived_dimension Volume ๐‹^3 true +@derived_dimension Density ๐Œ/๐‹^3 true +@derived_dimension Frequency inv(๐“) true +@derived_dimension Velocity ๐‹/๐“ true +@derived_dimension Acceleration ๐‹/๐“^2 true +@derived_dimension Force ๐Œ*๐‹/๐“^2 true +@derived_dimension Pressure ๐Œ*๐‹^-1*๐“^-2 true +@derived_dimension Energy ๐Œ*๐‹^2/๐“^2 true +@derived_dimension Momentum ๐Œ*๐‹/๐“ true +@derived_dimension Power ๐‹^2*๐Œ*๐“^-3 true +@derived_dimension Charge ๐ˆ*๐“ true +@derived_dimension Voltage ๐ˆ^-1*๐‹^2*๐Œ*๐“^-3 true +@derived_dimension ElectricalResistance ๐ˆ^-2*๐‹^2*๐Œ*๐“^-3 true +@derived_dimension ElectricalResistivity ๐ˆ^-2*๐‹^3*๐Œ*๐“^-3 true +@derived_dimension ElectricalConductance ๐ˆ^2*๐‹^-2*๐Œ^-1*๐“^3 true +@derived_dimension ElectricalConductivity ๐ˆ^2*๐‹^-3*๐Œ^-1*๐“^3 true +@derived_dimension Capacitance ๐ˆ^2*๐‹^-2*๐Œ^-1*๐“^4 true +@derived_dimension Inductance ๐ˆ^-2*๐‹^2*๐Œ*๐“^-2 true +@derived_dimension MagneticFlux ๐ˆ^-1*๐‹^2*๐Œ*๐“^-2 true +@derived_dimension DField ๐ˆ*๐“/๐‹^2 true +@derived_dimension EField ๐‹*๐Œ*๐“^-3*๐ˆ^-1 true +@derived_dimension HField ๐ˆ/๐‹ true +@derived_dimension BField ๐ˆ^-1*๐Œ*๐“^-2 true +@derived_dimension Action ๐‹^2*๐Œ*๐“^-1 true +@derived_dimension DynamicViscosity ๐Œ*๐‹^-1*๐“^-1 true +@derived_dimension KinematicViscosity ๐‹^2*๐“^-1 true +@derived_dimension Wavenumber inv(๐‹) true +@derived_dimension ElectricDipoleMoment ๐‹*๐“*๐ˆ true +@derived_dimension ElectricQuadrupoleMoment ๐‹^2*๐“*๐ˆ true +@derived_dimension MagneticDipoleMoment ๐‹^2*๐ˆ true +@derived_dimension Molarity ๐/๐‹^3 true +@derived_dimension Molality ๐/๐Œ true +@derived_dimension MassFlow ๐Œ/๐“ true +@derived_dimension MolarFlow ๐/๐“ true +@derived_dimension VolumeFlow ๐‹^3/๐“ true # Define base units. This is not to imply g is the base SI unit instead of kg. # See the documentation for further details. # #key: Symbol Display Name Dimension Prefixes? -@refunit m "m" Meter ๐‹ true -@refunit s "s" Second ๐“ true -@refunit A "A" Ampere ๐ˆ true -@refunit K "K" Kelvin ๐šฏ true -@refunit cd "cd" Candela ๐‰ true +" Unitful.m +\nThe meter, the SI base unit of length. +\nDimension: [`Unitful.๐‹`](@ref)." +@refunit m "m" Meter ๐‹ true true +" Unitful.s +\nThe second, the SI base unit of time. +\nDimension: [`Unitful.๐“`](@ref)." +@refunit s "s" Second ๐“ true true +" Unitful.A +\nThe ampere, the SI base unit of electric current. +\nDimension: [`Unitful.๐ˆ`](@ref)." +@refunit A "A" Ampere ๐ˆ true true +" Unitful.K +\nThe kelvin, the SI base unit of thermodynamic temperature. +\nDimension: [`Unitful.๐šฏ`](@ref)." +@refunit K "K" Kelvin ๐šฏ true true +" Unitful.cd +\nThe candela, the SI base unit of luminous intensity. +\nDimension: [`Unitful.๐‰`](@ref)." +@refunit cd "cd" Candela ๐‰ true true +# the docs for all gram-based units are defined later, to ensure kg is the base unit. @refunit g "g" Gram ๐Œ true -@refunit mol "mol" Mole ๐ true +" Unitful.mol +\nThe mole, the SI base unit for amount of substance. +\nDimension: [`Unitful.๐`](@ref)." +@refunit mol "mol" Mole ๐ true true # Angles and solid angles -@unit sr "sr" Steradian 1 true -@unit rad "rad" Radian 1 true +" Unitful.sr +\nThe steradian, a unit of spherical angle. There are 4ฯ€ sr in a sphere. +\nDimension: [`Unitful.NoDims`](@ref)." +@unit sr "sr" Steradian 1 true true +" Unitful.rad +\nThe radian, a unit of angle. There are 2ฯ€ rad in a circle. +\nDimension: [`Unitful.NoDims`](@ref)." +@unit rad "rad" Radian 1 true true +" Unitful.ยฐ +\nThe degree, a unit of angle. There are 360ยฐ in a circle. +\nDimension: [`Unitful.NoDims`](@ref)." @unit ยฐ "ยฐ" Degree pi/180 false # For numerical accuracy, specific to the degree import Base: sind, cosd, tand, secd, cscd, cotd @@ -79,107 +121,435 @@ deg2rad(d::Quantity{T, NoDims, typeof(ยฐ)}) where {T} = deg2rad(ustrip(ยฐ, d))u" rad2deg(r::Quantity{T, NoDims, typeof(rad)}) where {T} = rad2deg(ustrip(rad, r))u"ยฐ" # SI and related units -@unit Hz "Hz" Hertz 1/s true -@unit N "N" Newton 1kg*m/s^2 true -@unit Pa "Pa" Pascal 1N/m^2 true -@unit J "J" Joule 1N*m true -@unit W "W" Watt 1J/s true -@unit C "C" Coulomb 1A*s true -@unit V "V" Volt 1W/A true -@unit ฮฉ "ฮฉ" Ohm 1V/A true -@unit S "S" Siemens 1/ฮฉ true -@unit F "F" Farad 1s^4*A^2/(kg*m^2) true -@unit H "H" Henry 1J/(A^2) true -@unit T "T" Tesla 1kg/(A*s^2) true -@unit Wb "Wb" Weber 1kg*m^2/(A*s^2) true -@unit lm "lm" Lumen 1cd*sr true -@unit lx "lx" Lux 1lm/m^2 true -@unit Bq "Bq" Becquerel 1/s true -@unit Gy "Gy" Gray 1J/kg true -@unit Sv "Sv" Sievert 1J/kg true -@unit kat "kat" Katal 1mol/s true +" Unitful.Hz +\nThe hertz, an SI unit of frequency, defined as 1 s^-1. +\nDimension: ๐“^-1. +\nSee also: [`Unitful.s`](@ref)." +@unit Hz "Hz" Hertz 1/s true true +" Unitful.N +\nThe newton, an SI unit of force, defined as 1 kg ร— m / s^2. +\nDimension: ๐‹ ๐Œ ๐“^-2. +\nSee also: [`Unitful.kg`](@ref), [`Unitful.m`](@ref), [`Unitful.s`](@ref)." +@unit N "N" Newton 1kg*m/s^2 true true +" Unitful.Pa +\nThe pascal, an SI unit of pressure, defined as 1 N / m^2. +\nDimension: ๐Œ ๐‹^-1 ๐“^-2. +\nSee also: [`Unitful.N`](@ref), [`Unitful.m`](@ref)." +@unit Pa "Pa" Pascal 1N/m^2 true true +" Unitful.J +\nThe joule, an SI unit of energy, defined as 1 N ร— m. +\nDimension: ๐‹^2 ๐Œ ๐“^-2. +\nSee also: [`Unitful.N`](@ref), [`Unitful.m`](@ref)." +@unit J "J" Joule 1N*m true true +" Unitful.W +\nThe watt, an SI unit of power, defined as 1 J / s. +\nDimension: ๐‹^2 ๐Œ ๐“^-3. +\nSee also: [`Unitful.J`](@ref), [`Unitful.s`](@ref)." +@unit W "W" Watt 1J/s true true +" Unitful.C +\nThe coulomb, an SI unit of electric charge, defined as 1 A ร— s. +\nDimension: ๐ˆ ๐“. +\nSee also: [`Unitful.A`](@ref), [`Unitful.s`](@ref)." +@unit C "C" Coulomb 1A*s true true +" Unitful.V +\nThe volt, an SI unit of electric potential, defined as 1 W / A. +\nDimension: ๐‹^2 ๐Œ ๐ˆ^-1 ๐“^-3. +\nSee also: [`Unitful.W`](@ref), [`Unitful.A`](@ref)" +@unit V "V" Volt 1W/A true true +" Unitful.โ„ฆ +\nThe ohm, an SI unit of electrical resistance, defined as 1 V / A. +\nDimension: ๐‹^2 ๐Œ ๐ˆ^-2 ๐“^-3. +\nSee also: [`Unitful.V`](@ref), [`Unitful.A`](@ref)." +@unit ฮฉ "ฮฉ" Ohm 1V/A true true +" Unitful.S +\nThe siemens, an SI unit of electrical conductance, defined as 1 ฮฉ^-1. +\nDimension: ๐ˆ^2 ๐“^3 ๐‹^-2 ๐Œ^-1. +\nSee also: [`Unitful.ฮฉ`](@ref)" +@unit S "S" Siemens 1/ฮฉ true true +" Unitful.F +\nThe farad, an SI unit of electrical capacitance, defined as 1 s^4 ร— A^2 / (kg ร— m^2). +\nDimension: ๐ˆ^2 ๐“^4 ๐‹^-2 ๐Œ^-1. +\nSee also: [`Unitful.s`](@ref), [`Unitful.A`](@ref), [`Unitful.kg`](@ref), [`Unitful.m`](@ref)." +@unit F "F" Farad 1s^4*A^2/(kg*m^2) true true +" Unitful.H +\nThe henry, an SI unit of electrical inductance, defined as 1 J / A^2. +\nDimension: ๐‹^2 ๐Œ ๐ˆ^-2 ๐“^-2. +\nSee also: [`Unitful.J`](@ref), [`Unitful.A`](@ref)." +@unit H "H" Henry 1J/(A^2) true true +" Unitful.T +\nThe tesla, an SI unit of magnetic B-field strength, defined as 1 kg / (A ร— s^2). +\nDimension: ๐Œ ๐ˆ^-1 ๐“^-2. +\nSee also: [`Unitful.kg`](@ref), [`Unitful.A`](@ref), [`Unitful.s`](@ref)." +@unit T "T" Tesla 1kg/(A*s^2) true true +" Unitful.Wb +\nThe weber, an SI unit of magnetic flux, defined as 1 kg ร— m^2 / (A ร— s^2). +\nDimension: ๐‹^2 ๐Œ ๐ˆ^-1 ๐“^-2. +\nSee also: [`Unitful.kg`](@ref), [`Unitful.m`](@ref), [`Unitful.A`](@ref), [`Unitful.s`](@ref)." +@unit Wb "Wb" Weber 1kg*m^2/(A*s^2) true true +" Unitful.lm +\nThe lumen, an SI unit of luminous flux, defined as 1 cd ร— sr. +\nDimension: [`Unitful.๐‰`](@ref). +\nSee also: [`Unitful.cd`](@ref), [`Unitful.sr`](@ref)." +@unit lm "lm" Lumen 1cd*sr true true +" Unitful.lx +\nThe lux, an SI unit of illuminance, defined as 1 lm / m^2. +\nDimension: ๐‰ ๐‹^-2. +\nSee also: [`Unitful.lm`](@ref), [`Unitful.m`](@ref)." +@unit lx "lx" Lux 1lm/m^2 true true +" Unitful.Bq +\nThe becquerel, an SI unit of radioactivity, defined as 1 nuclear decay per s. +\nDimension: ๐“^-1. +\nSee also: [`Unitful.s`](@ref)." +@unit Bq "Bq" Becquerel 1/s true true +" Unitful.Gy +\nThe gray, an SI unit of ionizing radiation dose, defined as the absorbtion of 1 J per kg of matter. +\nDimension: ๐‹^2 ๐“^-2. +\nSee also: [`Unitful.lm`](@ref), [`Unitful.m`](@ref)." +@unit Gy "Gy" Gray 1J/kg true true +" Unitful.Sv +\nThe sievert, an SI unit of the biological effect of an ionizing radiation dose. +Defined as the health effect of 1 Gy of radiation, scaled by a quality factor. +\nDimension: ๐‹^2 ๐“^-2. +\nSee also: [`Unitful.Gy`](@ref)." +@unit Sv "Sv" Sievert 1J/kg true true +" Unitful.kat +\nThe katal, an SI unit of catalytic activity, defined as 1 mol of catalyzed +substrate per s. +\nDimension: ๐ ๐“^-1. +\nSee also: [`Unitful.mol`](@ref), [`Unitful.s`](@ref)." +@unit kat "kat" Katal 1mol/s true true +" Unitful.percent +\nPercent, a unit meaning parts per hundred. Printed as \"%\". +\nDimension: [`Unitful.NoDims`](@ref)." @unit percent "%" Percent 1//100 false +" Unitful.permille +\nPermille, a unit meaning parts per thousand. Printed as \"โ€ฐ\". +\nDimension: [`Unitful.NoDims`](@ref)." @unit permille "โ€ฐ" Permille 1//1000 false +" Unitful.pertenthousand +\nPermyriad, a unit meaning parts per ten thousand. Printed as \"โ€ฑ\". +\nDimension: [`Unitful.NoDims`](@ref)." @unit pertenthousand "โ€ฑ" Pertenthousand 1//10000 false # Temperature +" Unitful.ยฐC +\nThe degree Celsius, an SI unit of temperature, defined such that 0 ยฐC = 273.15 K. +\nDimension: [`Unitful.๐šฏ`](@ref). +\nSee also: [`Unitful.K`](@ref)." @affineunit ยฐC "ยฐC" (27315//100)K # Common units of time +" Unitful.minute +\nThe minute, a unit of time defined as 60 s. The full name `minute` is used instead of the symbol `min` +to avoid confusion with the Julia function `min`. +\nDimension: [`Unitful.๐“`](@ref). +\nSee Also: [`Unitful.s`](@ref)." @unit minute "minute" Minute 60s false +" Unitful.hr +\nThe hour, a unit of time defined as 60 minutes. +\nDimension: [`Unitful.๐“`](@ref). +\nSee Also: [`Unitful.minute`](@ref)." @unit hr "hr" Hour 3600s false +" Unitful.d +\nThe day, a unit of time defined as 24 hr. +\nDimension: [`Unitful.๐“`](@ref). +\nSee Also: [`Unitful.hr`](@ref)." @unit d "d" Day 86400s false +" Unitful.wk +\nThe week, a unit of time, defined as 7 d. +\nDimension: [`Unitful.๐“`](@ref). +\nSee Also: [`Unitful.d`](@ref)." @unit wk "wk" Week 604800s false -@unit yr "yr" Year 31557600s true +" Unitful.yr +\nThe year, a unit of time, defined as 365.25 d. +\nDimension: [`Unitful.๐“`](@ref). +\nSee Also: [`Unitful.hr`](@ref)." +@unit yr "yr" Year 31557600s true true +" Unitful.rps +\nRevolutions per second, a unit of rotational speed, defined as 2ฯ€ rad / s. +\nDimension: ๐“^-1. +\nSee Also: [`Unitful.rad`](@ref), [`Unitful.s`](@ref)." @unit rps "rps" RevolutionsPerSecond 2ฯ€*rad/s false +" Unitful.rpm +\nRevolutions per minute, a unit of rotational speed, defined as 2ฯ€ rad / minute. +\nDimension: ๐“^-1. +\nSee Also: [`Unitful.minute`](@ref), [`Unitful.rad`](@ref)." @unit rpm "rpm" RevolutionsPerMinute 2ฯ€*rad/minute false # Area # The hectare is used more frequently than any other power-of-ten of an are. +" Unitful.a +\nThe are, a metric unit of area, defined as 100 m^2. +\nDimension: ๐‹^2. +\nSee Also: [`Unitful.m`](@ref)." @unit a "a" Are 100m^2 false +" Unitful.ha +\nThe hectare, a metric unit of area, defined as 100 a. +\nDimension: ๐‹^2. +\nSee Also: [`Unitful.a`](@ref)." const ha = Unitful.FreeUnits{(Unitful.Unit{:Are, ๐‹^2}(2, 1//1),), ๐‹^2}() -@unit b "b" Barn 100fm^2 true +" Unitful.b +\nThe barn, a metric unit of area, defined as 100 fm^2. +\nDimension: ๐‹^2. +\nSee Also: [`Unitful.fm`](@ref)." +@unit b "b" Barn 100fm^2 true true # Volume # `l` is also an acceptable symbol for liters +" Unitful.L + Unitful.l +\nThe liter, a metric unit of volume, defined as 1000 cm^3. +\nDimension: ๐‹^3. +\nSee Also: [`Unitful.cm`](@ref)." @unit L "L" Liter m^3//1000 true for p in (:y, :z, :a, :f, :p, :n, :ฮผ, :ยต, :m, :c, :d, Symbol(""), :da, :h, :k, :M, :G, :T, :P, :E, :Z, :Y) Core.eval(Unitful, :(const $(Symbol(p,:l)) = $(Symbol(p,:L)))) end +@doc @doc(L) l +for (k,v) in prefixdict + if k != 0 + sym_L = Symbol(v,:L) + sym_l = Symbol(v,:l) + docstring = """ + Unitful.$sym_L + Unitful.$sym_l + + A prefixed unit, equal to 10^$k L. + + Dimension: ๐‹^3. + + See also: [`Unitful.L`](@ref). + """ + run = quote @doc $docstring $sym_l; @doc $docstring $sym_L end + eval(run) + end +end # Molarity -@unit M "M" Molar 1mol/L true +" Unitful.M +\nA unit for measuring molar concentration, equal to 1 mol/L. +\nDimension: ๐ ๐‹^-3. +\nSee Also: [`Unitful.L`](@ref), [`Unitful.mol`](@ref)." +@unit M "M" Molar 1mol/L true true # Energy +" Unitful.q +\nA quantity equal to the elementary charge, the charge of a single electron, +with a value of exactly 1.602,176,634 ร— 10^-19 C. The letter `q` is used instead of `e` to avoid +confusion with Euler's number. +\nDimension: ๐ˆ ๐“. +\nSee Also: [`Unitful.C`](@ref)." const q = 1.602_176_634e-19*C # CODATA 2018; `e` means 2.718... -@unit eV "eV" eV q*V true +" Unitful.eV +\nThe electron-volt, a unit of energy, defined as q*V. +\nDimension: ๐‹^2 ๐Œ ๐“^-2. +\nSee also: [`Unitful.q`](@ref), [`Unitful.V`](@ref)." +@unit eV "eV" eV q*V true true # For convenience -@unit Hz2ฯ€ "Hz2ฯ€" AngHertz 2ฯ€/s true -@unit bar "bar" Bar 100000Pa true +" Unitful.Hz2ฯ€ +\nA unit for convenience in angular frequency, equal to 2ฯ€ Hz. +\nDimension: ๐“^-1. +\nSee also: [`Unitful.Hz`](@ref)." +@unit Hz2ฯ€ "Hz2ฯ€" AngHertz 2ฯ€/s true true +" Unitful.bar +\nThe bar, a metric unit of pressure, defined as 100 kPa. +\nDimension: ๐Œ ๐‹^-1 ๐“^-2. +\nSee also: [`Unitful.kPa`](@ref)." +@unit bar "bar" Bar 100000Pa true true +" Unitful.atm +\nThe standard atmosphere, a unit of pressure, defined as 101,325 Pa. +\nDimension: ๐Œ ๐‹^-1 ๐“^-2. +\nSee also: [`Unitful.Pa`](@ref)." @unit atm "atm" Atmosphere 101325Pa false -@unit Torr "Torr" Torr 101325Pa//760 true +" Unitful.Torr +\nThe torr, a unit of pressure, defined as 1/760 atm. +\nDimension: ๐Œ ๐‹^-1 ๐“^-2. +\nSee also: [`Unitful.atm`](@ref)." +@unit Torr "Torr" Torr 101325Pa//760 true true # Constants (2018 CODATA values) (uncertainties in final digits) +" Unitful.c0 +\nA quantity representing the speed of light in a vacuum, defined as exactly +2.997,924,58 ร— 10^8 m/s. +\n`Unitful.c0` is a quantity (with units `m/s`) whereas [`Unitful.c`](@ref) is a unit equal to `c0`. +\nDimension: ๐‹ ๐“^-1. +\nSee also: [`Unitful.m`](@ref), [`Unitful.s`](@ref)." const c0 = 299_792_458*m/s # exact +" Unitful.c +\nThe speed of light in a vacuum, a unit of speed, defined as exactly +2.997,924,58 ร— 10^8 m/s. +\n[`Unitful.c0`](@ref) is a quantity (with units `m/s`) whereas `Unitful.c` is a unit equal to `c0`. +\nDimension: ๐‹ ๐“^-1. +\nSee also: [`Unitful.m`](@ref), [`Unitful.s`](@ref)." @unit c "c" SpeedOfLight 1c0 false +" Unitful.ฮผ0 +\nA quantity representing the vacuum permeability constant, defined as 4ฯ€ ร— 10^-7 H / m. +\nDimension: ๐‹ ๐Œ ๐ˆ^-2 ๐“^-2. +\nSee also: [`Unitful.H`](@ref), [`Unitful.m`](@ref)." const ฮผ0 = 4ฯ€*(1//10)^7*H/m # exact (but gets promoted to Float64...) const ยต0 = ฮผ0 # magnetic constant +" Unitful.ฮต0 + Unitful.ฯต0 +\nA quantity representing the vacuum permittivity constant, defined as 1 / (ฮผ0 ร— c^2). +\nDimension: ๐ˆ^2 ๐“^4 ๐‹^-3 ๐Œ^-1. +\nSee also: [`Unitful.ฮผ0`](@ref), [`Unitful.c`](@ref)." const ษ›0 = 1/(ฮผ0*c^2) # exact, electric constant; changes here may affect -const ฯต0 = ษ›0 # test of issue 79. +@doc @doc(ษ›0) const ฯต0 = ษ›0 # test of issue 79. +" Unitful.Z0 +\nA quantity representing the impedance of free space, a constant defined as ฮผ0 ร— c. +\nDimension: ๐‹^2 ๐Œ ๐ˆ^-2 ๐“^-3. +\nSee also: [`Unitful.ฮผ0`](@ref), [`Unitful.c`](@ref)." const Z0 = ฮผ0*c # exact, impedance of free space +" Unitful.G +\nA quantity representing the universal gravitational constant, equal to +6.674,30 ร— 10^-11 m^3 / (kg ร— s^2) (the CODATA 2018 recommended value). +\nDimension: ๐‹^3 ๐Œ^-1 ๐“^-2. +\nSee also: [`Unitful.m`](@ref), [`Unitful.kg`](@ref), [`Unitful.s`](@ref)." const G = 6.674_30e-11*m^3/kg/s^2 # (15) gravitational constant +" Unitful.gn +\nA quantity representing the nominal acceleration due to gravity in a vacuum +near the surface of the earth, defined by standard to be exactly 9.806,65 m / s^2. +\n`Unitful.gn` is a quantity (with units `m/s^2`) whereas [`Unitful.ge`](@ref) is a unit equal to `gn`. +\nDimension: ๐‹ ๐“^-2. +\nSee also: [`Unitful.m`](@ref), [`Unitful.s`](@ref)." const gn = 9.80665*m/s^2 # exact, standard acceleration of gravity +" Unitful.h +\nA quantity representing Planck's constant, defined as exactly +6.626,070,15 ร— 10^-34 J ร— s. +\nDimension: ๐‹^2 ๐Œ ๐“^-1. +\nSee also: [`Unitful.J`](@ref), [`Unitful.s`](@ref)." const h = 6.626_070_15e-34*J*s # exact, Planck constant +" Unitful.ฤง +\nA quantity representing the reduced Planck constant, defined as h / 2ฯ€. +\nDimension: ๐‹^2 ๐Œ ๐“^-1. +\nSee also: [`Unitful.h`](@ref)." const ฤง = h/2ฯ€ # hbar +" Unitful.ฮฆ0 +\nA quantity representing the superconducting magnetic flux quantum, defined as +h / (2 ร— q). +\nDimension: ๐‹^2 ๐Œ ๐ˆ^-1 ๐“^-2. +\nSee also: [`Unitful.h`](@ref), [`Unitful.q`](@ref)." const ฮฆ0 = h/(2q) # Superconducting magnetic flux quantum +" Unitful.me +\nA quantity representing the rest mass of an electron, equal to 9.109,383,7015 +ร— 10^-31 kg (the CODATA 2018 recommended value). +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee also: [`Unitful.kg`](@ref)." const me = 9.109_383_7015e-31*kg # (28) electron rest mass +" Unitful.mn +\nA quantity representing the rest mass of a neutron, equal to 1.674,927,498,04 +ร— 10^-27 kg (the CODATA 2018 recommended value). +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee also: [`Unitful.kg`](@ref)." const mn = 1.674_927_498_04e-27*kg # (95) neutron rest mass +" Unitful.mp +\nA quantity representing the rest mass of a proton, equal to 1.672,621,923,69 +ร— 10^-27 kg (the CODATA 2018 recommended value). +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee also: [`Unitful.kg`](@ref)." const mp = 1.672_621_923_69e-27*kg # (51) proton rest mass +" Unitful.ฮผB +\nA quantity representing the Bohr magneton, equal to q ร— ฤง / (2 ร— me). +\nDimension: ๐ˆ ๐‹^2. +\nSee also: [`Unitful.q`](@ref), [`Unitful.ฤง`](@ref), [`Unitful.me`](@ref)." const ฮผB = q*ฤง/(2*me) # Bohr magneton const ยตB = ฮผB +" Unitful.Na +\nA quantity representing Avogadro's constant, defined as exactly +6.022,140,76 ร— 10^23 / mol. +\nDimension: ๐^-1. +\nSee also: [`Unitful.mol`](@ref)." const Na = 6.022_140_76e23/mol # exact, Avogadro constant +" Unitful.k +\nA quantity representing the Boltzmann constant, defined as exactly +1.380,649 ร— 10^-23 J / K. +\nDimension: ๐‹^2 ๐Œ ๐šฏ^-1 ๐“^-2. +\nSee also: [`Unitful.J`](@ref), [`Unitful.K`](@ref)." const k = 1.380_649e-23*(J/K) # exact, Boltzmann constant +" Unitful.R +\nA quantity representing the molar gas constant, defined as +Na ร— k. +\nDimension: ๐‹^2 ๐Œ ๐^-1 ๐šฏ^-1 ๐“^-2. +\nSee also: [`Unitful.Na`](@ref), [`Unitful.k`](@ref)." const R = Na*k # molar gas constant +" Unitful.ฯƒ +\nA quantity representing the Stefan-Boltzmann constant, defined as +ฯ€^2 ร— k^4 / (60 ร— ฤง^3 ร— c^2). +\nDimension: ๐Œ ๐šฏ^-4 ๐“^-3. +\nSee also: [`Unitful.k`](@ref), [`Unitful.ฤง`](@ref), [`Unitful.c`](@ref)." const ฯƒ = ฯ€^2*k^4/(60*ฤง^3*c^2) # Stefan-Boltzmann constant +" Unitful.Rโˆž +\nA quantity representing the Rydberg constant, equal to 1.097,373,156,8160 ร— 10^-7 / m +(the CODATA 2018 recommended value). +\nDimension: ๐‹^-1. +\nSee also: [`Unitful.m`](@ref)." const Rโˆž = 10_973_731.568_160/m # (21) Rydberg constant +" Unitful.u +\nThe unified atomic mass unit, or dalton, a unit of mass defined as 1/12 the +mass of an unbound neutral atom of carbon-12, equal to 1.660,539,066,60 ร— 10^-27 kg +(the CODATA 2018 recommended value). +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee Also: [`Unitful.kg`](@ref)." @unit u "u" UnifiedAtomicMassUnit 1.660_539_066_60e-27*kg false # (50) # Acceleration +" Unitful.ge +\nThe nominal acceleration due to gravity in a vacuum near the surface of the +earth, a unit of acceleration, defined by standard to be exactly 9.806,65 m / s^2. +\n[`Unitful.gn`](@ref) is a quantity (with units `m/s^2`) whereas `Unitful.ge` is a unit equal to `gn`. +\nDimension: ๐‹ ๐“^-2. +\nSee also: [`Unitful.m`](@ref), [`Unitful.s`](@ref)." @unit ge "ge" EarthGravity gn false # CGS units -@unit Gal "Gal" Gal 1cm/s^2 true -@unit dyn "dyn" Dyne 1g*cm/s^2 true -@unit erg "erg" Erg 1g*cm^2/s^2 true -@unit Ba "Ba" Barye 1g/cm/s^2 true -@unit P "P" Poise 1g/cm/s true -@unit St "St" Stokes 1cm^2/s true -@unit Gauss "Gauss" Gauss (1//10_000)*T true -@unit Oe "Oe" Oersted (1_000/4ฯ€)*A/m true -@unit Mx "Mx" Maxwell (1//100_000_000)*Wb true +" Unitful.Gal +\nThe gal, a CGS unit of acceleration, defined as 1 cm / s^2. +\nDimension: ๐‹ ๐“^-2. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.s`](@ref)." +@unit Gal "Gal" Gal 1cm/s^2 true true +" Unitful.dyn +\nThe dyne, a CGS unit of force, defined as 1 g ร— cm / s^2. +\nDimension: ๐‹ ๐Œ ๐“^-2. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.s`](@ref), [`Unitful.g`](@ref)." +@unit dyn "dyn" Dyne 1g*cm/s^2 true true +" Unitful.erg +\nThe erg, a CGS unit of energy, defined as 1 dyn ร— cm. +\nDimension: ๐‹^2 ๐Œ ๐“^-2. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.dyn`](@ref)" +@unit erg "erg" Erg 1g*cm^2/s^2 true true +" Unitful.Ba +\nThe barye, a CGS unit of pressure, defined as 1 dyn / cm^2. +\nDimension: ๐Œ ๐‹^-1 ๐“^-2. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.dyn`](@ref)" +@unit Ba "Ba" Barye 1g/cm/s^2 true true +" Unitful.P +\nThe poise, a CGS unit of dynamic viscosity, defined as 1 dyn ร— s / cm^2. +\nDimension: ๐Œ ๐‹^-1 ๐“^-1. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.dyn`](@ref), [`Unitful.s`](@ref)" +@unit P "P" Poise 1g/cm/s true true +" Unitful.St +\nThe stokes, a CGS unit of kinematic viscosity, defined as 1 cm^2 / s. +\nDimension: ๐Œ^2 ๐“^-1. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.s`](@ref)" +@unit St "St" Stokes 1cm^2/s true true +" Unitful.Gauss +\nThe gauss, a CGS unit of magnetic B-field strength, defined as 1 Mx / cm^2. +\nDimension: ๐Œ ๐ˆ^-1 ๐“^-2. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.Mx`](@ref)" +@unit Gauss "Gauss" Gauss (1//10_000)*T true true +" Unitful.Oe +\nThe oersted, a CGS unit of magnetic H-field strength, defined as 1000 A / (4ฯ€ ร— m). +\nDimension: ๐ˆ ๐‹^-1. +\nSee also: [`Unitful.A`](@ref), [`Unitful.m`](@ref)" +@unit Oe "Oe" Oersted (1_000/4ฯ€)*A/m true true +" Unitful.Mx +\nThe maxwell, a CGS unit of magnetic flux, defined as 1 Gauss ร— cm^2. +\nDimension: ๐‹^2 ๐Œ ๐ˆ^-1 ๐“^-2. +\nSee also: [`Unitful.cm`](@ref), [`Unitful.Gauss`](@ref)" +@unit Mx "Mx" Maxwell (1//100_000_000)*Wb true true ######### @@ -187,38 +557,111 @@ const Rโˆž = 10_973_731.568_160/m # (21) Rydberg constant # Length #key: Symbol Display Name Equivalent to 10^n prefixes? +" Unitful.inch +\nThe inch, a US customary unit of length defined as 2.54 cm. +\nDimension: [`Unitful.๐‹`](@ref). +\nSee Also: [`Unitful.cm`](@ref)." @unit inch "inch" Inch (254//10000)*m false +" Unitful.mil +\nThe mil, a US customary unit of length defined as 1/1000 inch. +\nDimension: [`Unitful.๐‹`](@ref). +\nSee Also: [`Unitful.inch`](@ref)." @unit mil "mil" Mil (1//1000)*inch false +" Unitful.ft +\nThe foot, a US customary unit of length defined as 12 inch. +\nDimension: [`Unitful.๐‹`](@ref). +\nSee Also: [`Unitful.inch`](@ref)." @unit ft "ft" Foot 12inch false +" Unitful.yd +\nThe yard, a US customary unit of length defined as 3 ft. +\nDimension: [`Unitful.๐‹`](@ref). +\nSee Also: [`Unitful.ft`](@ref)." @unit yd "yd" Yard 3ft false +" Unitful.mi +\nThe mile, a US customary unit of length defined as 1760 yd. +\nDimension: [`Unitful.๐‹`](@ref). +\nSee Also: [`Unitful.yd`](@ref)." @unit mi "mi" Mile 1760yd false +" Unitful.angstrom + Unitful.โ„ซ +\nThe angstrom, a metric unit of length defined as 1/10 nm. +\nDimension: [`Unitful.๐‹`](@ref). +\nSee Also: [`Unitful.nm`](@ref)." @unit angstrom "โ„ซ" Angstrom (1//10)*nm false # U+00c5 (opt-shift-A on macOS) and U+212b ('\Angstrom' in REPL) look identical: -const ร… = โ„ซ = angstrom +@doc @doc(angstrom) const ร… = โ„ซ = angstrom # Area +" Unitful.ac +\nThe acre, a US customary unit of area defined as 4840 yd^2. +\nDimension: ๐‹^2. +\nSee Also: [`Unitful.yd`](@ref)." @unit ac "ac" Acre (316160658//78125)*m^2 false # Temperatures +" Unitful.Ra +\nThe rankine, a US customary unit of temperature defined as 5/9 K. +\nDimension: [`Unitful.๐šฏ`](@ref). +\nSee Also: [`Unitful.K`](@ref)." @unit Ra "Ra" Rankine (5//9)*K false +" Unitful.ยฐF +\nThe degree Fahrenheit, a US customary unit of temperature, defined such that 0 ยฐF = 459.67 Ra. +\nDimension: [`Unitful.๐šฏ`](@ref). +\nSee also: [`Unitful.Ra`](@ref)." @affineunit ยฐF "ยฐF" (45967//100)Ra # Masses +" Unitful.lb +\nThe pound-mass, a US customary unit of mass defined as exactly 0.453,592,37 kg. +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee Also: [`Unitful.kg`](@ref)." @unit lb "lb" Pound 0.45359237kg false # is exact +" Unitful.oz +\nThe ounce, a US customary unit of mass defined as 1/16 lb. +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee Also: [`Unitful.lb`](@ref)." @unit oz "oz" Ounce lb//16 false +" Unitful.slug +\nThe slug, a US customary unit of mass defined as 1 lbf ร— s^2 / ft. +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee Also: [`Unitful.lbf`](@ref), [`Unitful.s`](@ref), [`Unitful.ft`](@ref)." @unit slug "slug" Slug 1lb*ge*s^2/ft false +" Unitful.dr +\nThe dram, a US customary unit of mass defined as 1/16 oz. +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee Also: [`Unitful.oz`](@ref)." @unit dr "dr" Dram oz//16 false +" Unitful.gr +\nThe grain, a US customary unit of mass defined as 1/7000 lb. +\nDimension: [`Unitful.๐Œ`](@ref). +\nSee Also: [`Unitful.lb`](@ref)." @unit gr "gr" Grain (32//875)*dr false # Force +" Unitful.lbf +\nThe pound-force, a US customary unit of force defined as 1 lb ร— ge. +\nDimension: ๐‹ ๐Œ ๐“^-2. +\nSee Also: [`Unitful.lb`](@ref), [`Unitful.ge`](@ref)." @unit lbf "lbf" PoundsForce 1lb*ge false # Energy # Use ISO 31-4 for BTU definition -@unit cal "cal" Calorie 4.184J true +" Unitful.cal +\nThe calorie, a unit of energy defined as exactly 4.184 J. +\nDimension: ๐‹^2 ๐Œ ๐“^-2. +\nSee Also: [`Unitful.J`](@ref)." +@unit cal "cal" Calorie 4.184J true true +" Unitful.btu +\nThe British thermal unit, a US customary unit of heat defined by ISO 31-4 as exactly 1055.06 J. +\nDimension: ๐‹^2 ๐Œ ๐“^-2. +\nSee Also: [`Unitful.J`](@ref)." @unit btu "btu" BritishThermalUnit 1055.06J false # Pressure +" Unitful.psi +\nPounds per square inch, a US customary unit of pressure defined as 1 lbf / inch^2. +\nDimension: ๐Œ ๐‹^-1 ๐“^-2. +\nSee Also: [`Unitful.lbf`](@ref), [`Unitful.inch`](@ref)." @unit psi "psi" PoundsPerSquareInch 1lbf/inch^2 false ######### @@ -295,6 +738,27 @@ end ######### preferunits(kg) # others done in @refunit +# Fix documentation for all kg based units +for (k,v) in prefixdict + if k != 3 + sym = Symbol(v,:g) + docstring = """ + Unitful.$sym + + A prefixed unit, equal to 10^$(k-3) kg. Note that `kg`, not `g`, is the base unit. + + Dimension: [`Unitful.๐Œ`](@ref). + + See also: [`Unitful.kg`](@ref). + """ + run = quote @doc $docstring $sym end + eval(run) + end +end +@doc " Unitful.kg +\nThe kilogram, the SI base unit of mass. +Note that `kg`, not `g`, is the base unit. +\nDimension: [`Unitful.๐Œ`](@ref)." kg """ Unitful.promote_to_derived() diff --git a/src/types.jl b/src/types.jl index 05b76f61..bfff4d46 100644 --- a/src/types.jl +++ b/src/types.jl @@ -27,6 +27,8 @@ end Instances of this object represent dimensions, possibly combinations thereof. """ struct Dimensions{N} <: Unitlike end +" Unitful.NoDims +\nA dimension representing quantities without dimensions." const NoDims = Dimensions{()}() """ diff --git a/src/user.jl b/src/user.jl index 50a62783..e91d8346 100644 --- a/src/user.jl +++ b/src/user.jl @@ -26,7 +26,7 @@ function register(unit_module::Module) end """ - @dimension(symb, abbr, name) + @dimension(symb, abbr, name, autodocs=false) Creates new dimensions. `name` will be used like an identifier in the type parameter for a [`Unitful.Dimension`](@ref) object. `symb` will be a symbol defined in the namespace from which this macro is called that is bound to a @@ -43,6 +43,12 @@ of the newly defined dimension. The type alias for quantities or levels is simpl `name`, and the type alias for units is given by `name*"Units"`, e.g. `LengthUnits`. Note that there is also `LengthFreeUnits`, for example, which is an alias for dispatching on `FreeUnits` with length dimensions. The aliases are not exported. +If `autodocs == true`, docstrings will be automatically generated for these aliases. + +!!! compat "Unitful 1.10" + Documenting the resulting dimension symbol by adding a docstring before the `@dimension` + call requires Unitful 1.10 or later. The `autodocs` argument also requires Unitful 1.10 + or later. Finally, if you define new dimensions with [`@dimension`](@ref) you will need to specify a preferred unit for that dimension with [`Unitful.preferunits`](@ref), @@ -53,28 +59,64 @@ Returns the `Dimensions` object to which `symb` is bound. Usage example from `src/pkgdefaults.jl`: `@dimension ๐‹ "๐‹" Length` """ -macro dimension(symb, abbr, name) +macro dimension(symb, abbr, name, autodocs=false) s = Symbol(symb) x = Expr(:quote, name) uname = Symbol(name,"Units") funame = Symbol(name,"FreeUnits") + name_links = __module__ == Unitful ? "[`Unitful.Quantity`](@ref), [`Unitful.Level`](@ref)" : "`Unitful.Quantity`, `Unitful.Level`" + unit_links = __module__ == Unitful ? "[`Unitful.Units`](@ref)" : "`Unitful.Units`" + funit_links = __module__ == Unitful ? "[`Unitful.FreeUnits`](@ref)" : "`Unitful.FreeUnits`" + name_doc = """ + $__module__.$name{T, U} + + A supertype for quantities and levels of dimension [`$__module__.$s`](@ref) with a value + of type `T` and units `U`. + + See also: [`$__module__.$s`](@ref), $name_links. + """ + unit_doc = """ + $__module__.$uname{U} + + A supertype for units of dimension [`$__module__.$s`](@ref). Equivalent to + `Unitful.Units{U, $__module__.$s}`. + + See also: [`$__module__.$s`](@ref), $unit_links. + """ + funit_doc = """ + $__module__.$funame{U} + + A supertype for $funit_links of dimension [`$__module__.$s`](@ref). Equivalent to + `Unitful.FreeUnits{U, $__module__.$s}`. + + See also: [`$__module__.$s`](@ref). + """ esc(quote $Unitful.abbr(::$Dimension{$x}) = $abbr - const global $s = $Dimensions{($Dimension{$x}(1),)}() + Base.@__doc__ const global $s = $Dimensions{($Dimension{$x}(1),)}() const global ($name){T,U} = Union{ $Quantity{T,$s,U}, $Level{L,S,$Quantity{T,$s,U}} where {L,S}} const global ($uname){U} = $Units{U,$s} const global ($funame){U} = $FreeUnits{U,$s} + if $autodocs + @doc $name_doc $name + @doc $unit_doc $uname + @doc $funit_doc $funame + end $s end) end """ - @derived_dimension(name, dims) + @derived_dimension(name, dims, autodocs=false) Creates type aliases to allow dispatch on [`Unitful.Quantity`](@ref), [`Unitful.Level`](@ref), and [`Unitful.Units`](@ref) objects of a derived dimension, like area, which is just length squared. The type aliases are not exported. +If `autodocs == true`, docstrings will be automatically generated for these aliases. + +!!! compat "Unitful 1.10" + The `autodocs` argument requires Unitful 1.10 or later. `dims` is a [`Unitful.Dimensions`](@ref) object. @@ -85,22 +127,51 @@ Usage examples: - `@derived_dimension Area ๐‹^2` gives `Area` and `AreaUnit` type aliases - `@derived_dimension Speed ๐‹/๐“` gives `Speed` and `SpeedUnit` type aliases """ -macro derived_dimension(name, dims) +macro derived_dimension(name, dims, autodocs=false) uname = Symbol(name,"Units") funame = Symbol(name,"FreeUnits") + name_links = __module__ == Unitful ? "[`Unitful.Quantity`](@ref), [`Unitful.Level`](@ref)" : "`Unitful.Quantity`, `Unitful.Level`" + unit_links = __module__ == Unitful ? "[`Unitful.Units`](@ref)" : "`Unitful.Units`" + funit_links = __module__ == Unitful ? "[`Unitful.FreeUnits`](@ref)" : "`Unitful.FreeUnits`" + name_doc = """ + $__module__.$name{T, U} + + A supertype for quantities and levels of dimension `$dims` with a value of type `T` and + units `U`. + + See also: $name_links. + """ + unit_doc = """ + $__module__.$uname{U} + + A supertype for units of dimension `$dims`. Equivalent to `Unitful.Units{U, $dims}`. + + See also: $unit_links. + """ + funit_doc = """ + $__module__.$funame{U} + + A supertype for $funit_links of dimension `$dims`. Equivalent to + `Unitful.FreeUnits{U, $dims}`. + """ esc(quote const global ($name){T,U} = Union{ $Quantity{T,$dims,U}, $Level{L,S,$Quantity{T,$dims,U}} where {L,S}} const global ($uname){U} = $Units{U,$dims} const global ($funame){U} = $FreeUnits{U,$dims} + if $autodocs + @doc $name_doc $name + @doc $unit_doc $uname + @doc $funit_doc $funame + end nothing end) end """ - @refunit(symb, name, abbr, dimension, tf) + @refunit(symb, name, abbr, dimension, tf, autodocs=false) Define a reference unit, typically SI. Rather than define conversion factors between each and every unit of a given dimension, conversion factors are given between each unit and a reference unit, defined by this macro. @@ -109,7 +180,12 @@ This macro extends [`Unitful.abbr`](@ref) so that the reference unit can be displayed in an abbreviated format. If `tf == true`, this macro generates symbols for every power of ten of the unit, using the standard SI prefixes. A `dimension` must be given ([`Unitful.Dimensions`](@ref) object) that specifies the dimension -of the reference unit. +of the reference unit. If `autodocs == true`, autogenerated docstrings for +SI-prefixed units will be added. This option has no effect when 'tf == false'. + +!!! compat "Unitful 1.10" + Documenting the resulting unit by adding a docstring before the `@refunit` call requires + Unitful 1.10 or later. The `autodocs` argument also requires Unitful 1.10 or later. In principle, users can use this macro, but it probably does not make much sense to do so. If you define a new (probably unphysical) dimension using @@ -128,7 +204,7 @@ Usage example: `@refunit m "m" Meter ๐‹ true` This example, found in `src/pkgdefaults.jl`, generates `km`, `m`, `cm`, ... """ -macro refunit(symb, abbr, name, dimension, tf) +macro refunit(symb, abbr, name, dimension, tf, autodocs=false) expr = Expr(:block) n = Meta.quot(Symbol(name)) @@ -138,11 +214,11 @@ macro refunit(symb, abbr, name, dimension, tf) if tf push!(expr.args, quote - $Unitful.@prefixed_unit_symbols $symb $name $dimension (1.0, 1) + Base.@__doc__ $Unitful.@prefixed_unit_symbols $symb $name $dimension (1.0, 1) $autodocs end) else push!(expr.args, quote - $Unitful.@unit_symbols $symb $name $dimension (1.0, 1) + Base.@__doc__ $Unitful.@unit_symbols $symb $name $dimension (1.0, 1) end) end @@ -155,10 +231,16 @@ macro refunit(symb, abbr, name, dimension, tf) end """ - @unit(symb,abbr,name,equals,tf) + @unit(symb,abbr,name,equals,tf,autodocs=false) Define a unit. Rather than specifying a dimension like in [`@refunit`](@ref), `equals` should be a [`Unitful.Quantity`](@ref) equal to one of the unit being defined. If `tf == true`, symbols will be made for each power-of-ten prefix. +If `autodocs == true`, autogenerated docstrings for SI-prefixed units will be added. +This option has no effect when `tf == false`. + +!!! compat "Unitful 1.10" + Documenting the resulting unit by adding a docstring before the `@unit` call requires + Unitful 1.10 or later. The `autodocs` argument also requires Unitful 1.10 or later. Returns the [`Unitful.FreeUnits`](@ref) object to which `symb` is bound. @@ -166,7 +248,7 @@ Usage example: `@unit mi "mi" Mile (201168//125)*m false` This example will *not* generate `kmi` (kilomiles). """ -macro unit(symb,abbr,name,equals,tf) +macro unit(symb,abbr,name,equals,tf,autodocs=false) expr = Expr(:block) n = Meta.quot(Symbol(name)) @@ -180,11 +262,11 @@ macro unit(symb,abbr,name,equals,tf) if tf push!(expr.args, quote - $Unitful.@prefixed_unit_symbols $symb $name $d $basef + Base.@__doc__ $Unitful.@prefixed_unit_symbols $symb $name $d $basef $autodocs end) else push!(expr.args, quote - $Unitful.@unit_symbols $symb $name $d $basef + Base.@__doc__ $Unitful.@unit_symbols $symb $name $d $basef end) end @@ -200,11 +282,15 @@ end Macro for easily defining affine units. `offset` gives the zero of the relative scale in terms of an absolute scale; the scaling is the same as the absolute scale. Example: `@affineunit ยฐC "ยฐC" (27315//100)K` is used internally to define degrees Celsius. + +!!! compat "Unitful 1.10" + Documenting the resulting unit by adding a docstring before the `@affineunit` call + requires Unitful 1.10 or later. """ macro affineunit(symb, abbr, offset) s = Symbol(symb) return esc(quote - const global $s = $affineunit($offset) + Base.@__doc__ const global $s = $affineunit($offset) $Base.show(io::$IO, ::$genericunit($s)) = $print(io, $abbr) end) end @@ -224,23 +310,46 @@ function basefactors_expr(m::Module, n, basefactor) end """ - @prefixed_unit_symbols(symb,name,dimension,basefactor) + @prefixed_unit_symbols(symb,name,dimension,basefactor,autodocs=false) Not called directly by the user. Given a unit symbol and a unit's name, -will define units for each possible SI power-of-ten prefix on that unit. +will define units for each possible SI power-of-ten prefix on that unit. If +`autodocs == true`, it will automatically generate docstrings for these units. -Example: `@prefixed_unit_symbols m Meter ๐‹ (1.0,1)` results in `nm`, `cm`, `m`, `km`, ... -all getting defined in the calling namespace. +!!! compat "Unitful 1.10" + Documenting the resulting unit by adding a docstring before the `@prefixed_unit_symbols` + call requires Unitful 1.10 or later. The `autodocs` argument also requires Unitful 1.10 + or later. + +Example: `@prefixed_unit_symbols m Meter ๐‹ (1.0,1) true` results in `nm`, `cm`, `m`, `km`, ... +all getting defined in the calling namespace, with docstrings automatically defined for SI-prefixed units. """ -macro prefixed_unit_symbols(symb,name,user_dimension,basefactor) +macro prefixed_unit_symbols(symb,name,user_dimension,basefactor,autodocs=false) expr = Expr(:block) n = Meta.quot(Symbol(name)) for (k,v) in prefixdict s = Symbol(v,symb) u = :($Unit{$n, $user_dimension}($k,1//1)) - ea = quote - $(basefactors_expr(__module__, n, basefactor)) - const global $s = $FreeUnits{($u,), $dimension($u), $nothing}() + if k == 0 + ea = quote + $(basefactors_expr(__module__, n, basefactor)) + Base.@__doc__ const global $s = $FreeUnits{($u,), $dimension($u), $nothing}() + end + else + docstring1 = """ + $__module__.$s + + A prefixed unit, equal to 10^$k $symb. + + Dimension: """ + docstring2 = "\n\nSee also: [`$__module__.$symb`](@ref)." + ea = quote + $(basefactors_expr(__module__, n, basefactor)) + const global $s = $FreeUnits{($u,), $dimension($u), $nothing}() + if $autodocs + @doc $docstring1*string($user_dimension)*$docstring2 $s + end + end end push!(expr.args, ea) end @@ -261,6 +370,10 @@ end Not called directly by the user. Given a unit symbol and a unit's name, will define units without SI power-of-ten prefixes. +!!! compat "Unitful 1.10" + Documenting the resulting unit by adding a docstring before the `@unit_symbols` call + requires Unitful 1.10 or later. + Example: `@unit_symbols ft Foot ๐‹` results in `ft` getting defined but not `kft`. """ macro unit_symbols(symb,name,user_dimension,basefactor) @@ -269,7 +382,7 @@ macro unit_symbols(symb,name,user_dimension,basefactor) u = :($Unit{$n, $user_dimension}(0,1//1)) esc(quote $(basefactors_expr(__module__, n, basefactor)) - const global $s = $FreeUnits{($u,), $dimension($u), $nothing}() + Base.@__doc__ const global $s = $FreeUnits{($u,), $dimension($u), $nothing}() end) end diff --git a/test/runtests.jl b/test/runtests.jl index 3e96550c..4e2a7cad 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -1797,6 +1797,98 @@ end end end +module DocUnits + using Unitful + using Unitful: ๐‹ + "dimension docs" + @dimension ๐ƒ "๐ƒ" DocDimension true + @derived_dimension DerivedDocDimension ๐ƒ*๐‹ true + "refunit docs" + @refunit dRefFoo "dRefFoo" DRefFoo ๐ƒ true true + "unit docs" + @unit dFoo "dFoo" DFoo 1*dRefFoo*u"m" true true +end + +@testset "Docs" begin + @test string(@doc DocUnits.๐ƒ) == "dimension docs\n" + @test string(@doc DocUnits.dRefFoo) == "refunit docs\n" + @test string(@doc DocUnits.dFoo) == "unit docs\n" + @test string(@doc DocUnits.DocDimension) == """ + ``` + $(@__MODULE__).DocUnits.DocDimension{T, U} + ``` + + A supertype for quantities and levels of dimension [`$(@__MODULE__).DocUnits.๐ƒ`](@ref) with a value of type `T` and units `U`. + + See also: [`$(@__MODULE__).DocUnits.๐ƒ`](@ref), `Unitful.Quantity`, `Unitful.Level`. + """ + @test string(@doc DocUnits.DocDimensionUnits) == """ + ``` + $(@__MODULE__).DocUnits.DocDimensionUnits{U} + ``` + + A supertype for units of dimension [`$(@__MODULE__).DocUnits.๐ƒ`](@ref). Equivalent to `Unitful.Units{U, $(@__MODULE__).DocUnits.๐ƒ}`. + + See also: [`$(@__MODULE__).DocUnits.๐ƒ`](@ref), `Unitful.Units`. + """ + @test string(@doc DocUnits.DocDimensionFreeUnits) == """ + ``` + $(@__MODULE__).DocUnits.DocDimensionFreeUnits{U} + ``` + + A supertype for `Unitful.FreeUnits` of dimension [`$(@__MODULE__).DocUnits.๐ƒ`](@ref). Equivalent to `Unitful.FreeUnits{U, $(@__MODULE__).DocUnits.๐ƒ}`. + + See also: [`$(@__MODULE__).DocUnits.๐ƒ`](@ref). + """ + @test string(@doc DocUnits.DerivedDocDimension) == """ + ``` + $(@__MODULE__).DocUnits.DerivedDocDimension{T, U} + ``` + + A supertype for quantities and levels of dimension `๐ƒ * ๐‹` with a value of type `T` and units `U`. + + See also: `Unitful.Quantity`, `Unitful.Level`. + """ + @test string(@doc DocUnits.DerivedDocDimensionUnits) == """ + ``` + $(@__MODULE__).DocUnits.DerivedDocDimensionUnits{U} + ``` + + A supertype for units of dimension `๐ƒ * ๐‹`. Equivalent to `Unitful.Units{U, ๐ƒ * ๐‹}`. + + See also: `Unitful.Units`. + """ + @test string(@doc DocUnits.DerivedDocDimensionFreeUnits) == """ + ``` + $(@__MODULE__).DocUnits.DerivedDocDimensionFreeUnits{U} + ``` + + A supertype for `Unitful.FreeUnits` of dimension `๐ƒ * ๐‹`. Equivalent to `Unitful.FreeUnits{U, ๐ƒ * ๐‹}`. + """ + @test string(@doc DocUnits.kdFoo) == """ + ``` + $(@__MODULE__).DocUnits.kdFoo + ``` + + A prefixed unit, equal to 10^3 dFoo. + + Dimension: ๐ƒ ๐‹ + + See also: [`$(@__MODULE__).DocUnits.dFoo`](@ref). + """ + @test string(@doc DocUnits.kdRefFoo) == """ + ``` + $(@__MODULE__).DocUnits.kdRefFoo + ``` + + A prefixed unit, equal to 10^3 dRefFoo. + + Dimension: ๐ƒ + + See also: [`$(@__MODULE__).DocUnits.dRefFoo`](@ref). + """ +end + # Test precompiled Unitful extension modules load_path = mktempdir() load_cache_path = mktempdir()