Merge pull request #15 from co1emi11er2/unitful_pipe

Unitful pipe

Project.toml

@@ -1,7 +1,7 @@
 name = "Handcalcs"
 uuid = "e8a07092-c156-4455-ab8e-ed8bc81edefb"
 authors = ["Cole Miller"]
-version = "0.3.4"
+version = "0.4.0"
 
 [deps]
 AbstractTrees = "1520ce14-60c1-5f80-bbc7-55ef81b5835c"
@@ -18,13 +18,13 @@ TestHandcalcFunctions = "6ba57fb7-81df-4b24-8e8e-a3885b6fcae7"
 AbstractTrees = "0.4"
 CodeTracking = "1.3"
 LaTeXStrings = "1.3"
-Latexify = "0.16"
+Latexify = "^0.16.4"
 MacroTools = "0.5"
 PrecompileTools = "1.2"
 Revise = "3.5"
 TestHandcalcFunctions = "0.2"
 Unitful = "1.19"
-UnitfulLatexify = "1.6"
+UnitfulLatexify = "^1.6.4"
 julia = "1.10"
 
 [extras]

docs/Project.toml

@@ -1,6 +1,7 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Handcalcs = "e8a07092-c156-4455-ab8e-ed8bc81edefb"
+LiveServer = "16fef848-5104-11e9-1b77-fb7a48bbb589"
 TestHandcalcFunctions = "6ba57fb7-81df-4b24-8e8e-a3885b6fcae7"
 Unitful = "1986cc42-f94f-5a68-af5c-568840ba703d"
 UnitfulLatexify = "45397f5d-5981-4c77-b2b3-fc36d6e9b728"

docs/make.jl

@@ -16,6 +16,8 @@ makedocs(;
     ),
     pages=[
         "Home" => "index.md",
+        "Tutorial" => "tutorial.md",
+        "References" => "references.md",
     ],
 )
 

docs/src/index.md

@@ -6,200 +6,34 @@ CurrentModule = Handcalcs
 
 ## Introduction
 
-This is the documentation for [Handcalcs.jl](https://github.com/co1emi11er2/Handcalcs.jl). This package supplies macros to generate ``\LaTeX`` formatted strings from mathmatical formulas. This package takes inspiration from [handcalcs.py](https://github.com/connorferster/handcalcs) which is a python package that works best in jupyter notebooks. The goal is to get the functionalities of that package and bring them to Julia. At this point, I believe most (if not all) of the features from the python package are here. Future plans are to integrate the package with [Unitful.jl](https://painterqubits.github.io/Unitful.jl/stable/). This package is an extension of [Latexify.jl](https://github.com/korsbo/Latexify.jl). The `@latexdefine` macro is similar to the main `@handcalcs` macro, but instead of only a symbolic rendering it also renders the numeric substitution.
+This is the documentation for [Handcalcs.jl](https://github.com/co1emi11er2/Handcalcs.jl). This package supplies macros to generate ``\LaTeX`` formatted strings from mathmatical formulas. This package takes inspiration from [handcalcs.py](https://github.com/connorferster/handcalcs) which is a python package that works best in jupyter notebooks. The goal is to get the functionalities of that package and bring them to Julia. At this point, I believe most (if not all) of the features from the python package are here. This package is an extension of [Latexify.jl](https://github.com/korsbo/Latexify.jl). The `@latexdefine` macro is similar to the main `@handcalcs` macro, but instead of only a symbolic rendering it also renders the numeric substitution.
 
-**Note: This package now renders properly in Quarto/Weave!! You can change the default settings to your liking. See examples below.**
+The package can be used with [Unitful.jl](https://painterqubits.github.io/Unitful.jl/stable/) and can also be used with [Quarto](https://quarto.org/) to produce high quality calculations. See the [Flexural Design Example](https://github.com/co1emi11er2/Handcalcs.jl/blob/master/examples/Flexure%20Design/FlexureDesign.pdf) for an example.
 
-## Expression Examples
 
-### A single expression example:
-
-```@example main
-using Handcalcs
-a = 2
-b = -5
-c = 2
-@handcalcs x = (-b + sqrt(b^2 - 4*a*c))/ (2*a)
-```
-
-The variable x is still evaluated:
-
-```@example main
-x
-```
-
-### An example of multiple expressions:
-
-```@example main
-b = 5 # width
-h = 15 # height
-@handcalcs begin
-  I_x = (b*h^3)/12; "moment of inertia about x";
-  I_y = (h*b^3)/12; "moment of inertia about y";
-end
-```
-
-The `I_x` and `I_y` variables are still evaluated:
-
-```@example main
-println("The moment of inertia about the x direction is: $I_x\n
-The moment of inertia about the y direction is: $I_y\n")
-```
-
-### You can edit the layout of the returned LaTeX expression with `cols` and `spa`:
-
-- cols - change the number of columns the expression returns (default = 1).
-- spa - change the vertical line spacing between expressions (default = 10).
-- h_env - change the environment (default = "aligned").
-- len - change expression to write to multiple lines using `len=:long` (default = :short). 
-
-**Note: `@handcalcs` macro can also take symbols of defined variables. See below.**
-
-```@example main
-a, b, c = 1, 2, 3
-@handcalcs begin
-    a # see note above
-    b
-    c
-    x = 4
-    y = 5
-    z = 6
-end cols=3 spa=0
-```
-
-```@example main
-a, b, c = 2, -5, 2
-@handcalcs begin
-    x1 = (-b + sqrt(b^2 - 4*a*c))/(2*a)
-    x2 = (-b - sqrt(b^2 - 4*a*c))/(2*a)
-end len = :long # using len argument forces cols=1
-```
-
-## Function Examples
-
-The `@handcalcs` macro will now automatically try to "unroll" the expressions within a function when the expression has the following pattern: `variable = function_name(args...; kwargs...)`. Note that this is recursive, so if you have a function that calls other functions where the expressions that call the function are of the format mentioned, it will continue to step into each function to "unroll" all expressions.
-
-One issue that can arise are for the functions that you do not want to unroll. Consider the expression: `y = sin(x)` or ` y = x + 5`. Both of these expressions match the format: `variable = function_name(args...; kwargs...)` and would be unrolled. This would result in an error since these functions don't have generic math expressions that can be latexified defining the function. You will need to use the `not_funcs` keyword to manually tell the @handcalcs macro to pass over these functions. Some of the common math functions that you will not want to unroll are automatically passed over. See examples below.
-
-### An example for rendering expressions within a function:
-
-```@example other
-function calc_Ix(b, h) # function defined in TestHandcalcFunctions
-    Ix = b*h^3/12
-    return Ix
-end;
-```
-
-```@example main
-using TestHandcalcFunctions
-b = 5 # width
-h = 15 # height
-@handcalcs Ix = calc_Ix(b, h) # function is defined in TestHandcalcFunctions package
-```
-
-The `Ix` variable is evaluated. Ix being the variable assigned in the @handcalcs part (variables within function are not defined in the global name space). If you assign it to a different variable then that will be the variable defined (although you will still see it as Ix in the latex portion). Also note that return statements are filtered out of the function body, so keep relevant parts separate from return statements.
-
-```@example other
-function calc_Is(b, h) # function defined in TestHandcalcFunctions
-    Ix = calc_Ix(b, h)
-    Iy = calc_Iy(h, b)
-    return Ix, Iy
-end;
-```
-
-```@example main
-using TestHandcalcFunctions
-x = 0
-@handcalcs begin
-y = sin(x)
-z = cos(x)
-I_x, I_y = TestHandcalcFunctions.calc_Is(5, 15)
-end not_funcs = [:sin :cos]
-```
-
-In the above example `sin` and `cos` were passed over and calc_Is was not. As you can see, the calc_Is function was a function that called other functions, and the @handcalcs macro continued to step into each function to unroll all expressions. Please see below for a list of the current functions that are passed over automatically. Please submit a pull request if you would like to add more generic math functions that I have left out. 
+## Installation
+This package is registered in the Julia registry, so to install it you can just
+run:
 
 ```julia
-const math_syms = [
-    :*, :/, :^, :+, :-, :%,
-    :.*, :./, :.^, :.+, :.-, :.%,
-    :<, :>, Symbol(==), :<=, :>=,
-    :.<, :.>, :.==, :.<=, :.>=,
-    :sqrt, :sin, :cos, :tan, :sum, 
-    :cumsum, :max, :min, :exp, :log,
-    :log10]
-```
-
-If you want to add functions to your specific project, you can do the following:
-
-```@example main
-set_handcalcs(not_funcs = [:foo :bar :baz])
+Pkg.add("Handcalcs")
 ```
 
-Current Limitations for `@handcalcs`
-
-- I believe the function needs to be defined in another package. The @code_expr macro from CodeTracking.jl does not see functions in Main for some reason.
-- If the function has other function calls within it's body that are not available in Main, then the macro will error.
-
-### An example of changing default settings:
-
-You can change the default settings using the `set_handcalcs` function *(similar to the `set_default` function in Latexify)*.
-
-```julia
-set_handcalcs(cols=3)
-```
-
-Note that this changes Handcalcs.jl from within and should therefore only be used in your own Julia sessions (do not call this from within your packages).
-
-The calls are additive so that a new call with
-
-```julia
-set_handcalcs(spa = 5)
-```
+## Basic example:
 
-will not cancel out the changes we just made to `cols`. 
-
-To view your changes, use
-
-```julia
-get_handcalcs()
-```
-
-and to reset your changes, use
-
-```julia
-reset_handcalcs()
-```
-
-## Using Unitful with UnitfulLatexify
-
-The package has plans to work with the packages [Unitful.jl](https://painterqubits.github.io/Unitful.jl/stable/) and [UnitfulLatexify.jl](https://gustaphe.github.io/UnitfulLatexify.jl/stable/). The only issue known is the rendering of units under exponents. Parenthesis need to wrap the numerical value and the unit for it to display correctly. See example below.
+### Single line expression
 
 ```@example main
-using Unitful, UnitfulLatexify
-a = 2u"inch"
-b = -5u"inch"
-@handcalc c = sqrt(a^2 + b^2)
+using Handcalcs
+a = 3
+b = 4
+@handcalcs c = sqrt(a^2 + b^2)
 ```
 
-You can see that it looks as though only the unit is being squared. This should be an easy fix. See pull request made in Latexify.jl [here](https://github.com/korsbo/Latexify.jl/pull/280). The pull request has been up for a while, so not sure if it will get updated soon. You can always `dev Latexify` and add the one line change for now.
 
 ## Future Plans
 
 There are a number of things that I would like to implement to the package. Here is a list of features I hope to add:
 
-- Maybe add a way to change color of expressions.
 - Maybe a symbolic mode that would essentially be like @latexdefine but you get function unrolling and multiline support.
-- A way to disable @handcalcs macro if you are wanting to run script for multiple iterations and not worried about rendering all iterations. That way you get speed for those situations.
 - I have also thought about adding a setting that you could change if you were within the REPL and instead of latex (since it is not very readable) to instead output a simple string instead. For example: `I_x = b*h^3/12 = 5*15^3/12 = 1406.25`.
-
-
-
-## References
-
-```@index
-```
-
-```@autodocs
-Modules = [Handcalcs]
-```

docs/src/references.md

@@ -0,0 +1,23 @@
+# References
+
+## Disclaimer
+
+Note that there are 3 macros exported. It is recommended to use `@handcalcs` mainly. The singular `@handcalc` macro is used by the `@handcalcs` macro. You may find `@handcalc` useful on certain occasions where you don't define a variable. For example:
+
+```@example
+using Handcalcs
+a = 2
+b = 3
+@handcalc a + b
+```
+
+Besides this use case, `@handcalcs` macro can be used. The `@handfunc` macro should not be used anymore.
+
+## References
+
+```@index
+```
+
+```@autodocs
+Modules = [Handcalcs]
+```