[Wip] Refactor "src/dsl.jl" file

docs/src/api.md

@@ -100,6 +100,7 @@ of all options currently available.
 - [`continuous_events`](@ref constraint_equations_events): Allows the creation of continuous events.
 - [`discrete_events`](@ref constraint_equations_events): Allows the creation of discrete events.
 - [`combinatoric_ratelaws`](@ref faq_combinatoric_ratelaws): Takes a single option (`true` or `false`), which sets whether to use combinatorial rate laws.
+- [`require_declaration`](@ref dsl_advanced_options_require_dec): Turns off all inference of parameters, species, variables, the default differential, and observables (requiring these to be explicitly declared using e.g. `@species`).
 
 ## [ModelingToolkit and Catalyst accessor functions](@id api_accessor_functions)
 A [`ReactionSystem`](@ref) is an instance of a

docs/src/model_creation/dsl_advanced.md

@@ -204,7 +204,6 @@ ModelingToolkit.getdescription(two_state_system.kA)
 ```
 
 ### [Designating constant-valued/fixed species parameters](@id dsl_advanced_options_constant_species)
-
 Catalyst enables the designation of parameters as `constantspecies`. These parameters can be used as species in reactions, however, their values are not changed by the reaction and remain constant throughout the simulation (unless changed by e.g. the [occurrence of an event](@ref constraint_equations_events). Practically, this is done by setting the parameter's `isconstantspecies` metadata to `true`. Here, we create a simple reaction where the species `X` is converted to `Xᴾ` at rate `k`. By designating `X` as a constant species parameter, we ensure that its quantity is unchanged by the occurrence of the reaction.
 ```@example dsl_advanced_constant_species
 using Catalyst # hide
@@ -501,6 +500,34 @@ Catalyst.getdescription(rx)
 
 A list of all available reaction metadata can be found [in the api](@ref api_rx_metadata).
 
+## [Declaring individual reaction using the `@reaction` macro](@id dsl_advanced_options_reaction_macro)
+Catalyst exports a macro `@reaction` which can be used to generate a singular [`Reaction`](@ref) object of the same type which is stored within the [`ReactionSystem`](@ref) structure (which in turn can be generated by `@reaction_network `). In the following example, we create a simple [SIR model](@ref basic_CRN_library_sir). Next, we instead create its individual reaction components using the `@reaction` macro. Finally, we confirm that these are identical to those stored in the initial model (using the [`reactions`](@ref) function).
+```@example dsl_advanced_reaction_macro
+using Catalyst # hide
+sir_model = @reaction_network begin
+ α, S + I --> 2I
+ β, I --> R
+end
+infection_rx = @reaction α, S + I --> 2I
+recovery_rx = @reaction β, I --> R
+issetequal(reactions(sir_model), [infection_rx, recovery_rx])
+```
+
+Here, the `@reaction` macro is followed by a single line consisting of three parts:
+- A rate (at which the reaction occurs).
+- Any number of substrates (which are consumed by the reaction).
+- Any number of products (which are produced by the reaction).
+The rules of writing and interpreting this line are [identical to those for `@reaction_network`](@ref dsl_description_reactions) (however, bi-directional reactions are not permitted).
+
+Generally, the `@reaction` macro provides a more concise notation to the [`Reaction`](@ref) constructor. One of its primary uses is for [creating models programmatically](@ref programmatic_CRN_construction). When doing so, it can often be useful to use [*interpolation*](@ref dsl_advanced_options_symbolics_and_DSL_interpolation) of symbolic variables declared previously:
+```@example dsl_advanced_reaction_macro
+t = default_t()
+@parameters k b
+@species A(t)
+ex = k*A^2 + t
+rx = @reaction b*$ex*$A, $A --> C
+```
+
 ## [Working with symbolic variables and the DSL](@id dsl_advanced_options_symbolics_and_DSL)
 We have previously described how Catalyst represents its models symbolically (enabling e.g. symbolic differentiation of expressions stored in models). While Catalyst utilises this for many internal operation, these symbolic representations can also be accessed and harnessed by the user. Primarily, doing so is much easier during programmatic (as opposed to DSL-based) modelling. Indeed, the section on [programmatic modelling](@ref programmatic_CRN_construction) goes into more details about symbolic representation in models, and how these can be used. It is, however, also ways to utilise these methods during DSL-based modelling. Below we briefly describe two methods for doing so.
 

src/Catalyst.jl

@@ -72,11 +72,6 @@ const CONSERVED_CONSTANT_SYMBOL = :Γ
 const forbidden_symbols_skip = Set([:ℯ, :pi, :π, :t, :∅])
 const forbidden_symbols_error = union(Set([:im, :nothing, CONSERVED_CONSTANT_SYMBOL]),
     forbidden_symbols_skip)
-const forbidden_variables_error = let
-    fvars = copy(forbidden_symbols_error)
-    delete!(fvars, :t)
-    fvars
-end
 
 ### Package Main ###
 

src/chemistry_functionality.jl

@@ -86,7 +86,7 @@ function make_compound(expr)
     # Cannot extract directly using e.g. "getfield.(composition, :reactant)" because then
     # we get something like :([:C, :O]), rather than :([C, O]).
     composition = Catalyst.recursive_find_reactants!(expr.args[3], 1,
-        Vector{ReactantStruct}(undef, 0))
+        Vector{DSLReactant}(undef, 0))
     components = :([])                                      # Becomes something like :([C, O]).
     coefficients = :([])                                    # Becomes something like :([1, 2]).
     for comp in composition