[FileFormats.MOF] rename to use_nlp_block and add documentation

docs/src/submodules/FileFormats/overview.md

@@ -211,6 +211,28 @@ A Mathematical Programming System (MPS) model
 julia> read!(io, src_2);
 ```
 
+## ScalarNonlinearFunction
+
+By default, reading a `.nl` or `.mof.json` that contains nonlinear expressions
+will create an [`NLPBlock`](@ref).
+
+To instead read nonlinear expressions as [`ScalarNonlinearFunction`](@ref),
+pass the `use_nlp_block = false` keyword argument to the `Model` constructor:
+
+```jldoctest
+julia> model = MOI.FileFormats.Model(;
+           format = MOI.FileFormats.FORMAT_MOF,
+           use_nlp_block = false,
+       )
+A MathOptFormat Model
+
+julia> model = MOI.FileFormats.Model(;
+           format = MOI.FileFormats.FORMAT_NL,
+           use_nlp_block = false,
+       )
+An AMPL (.nl) model
+```
+
 ## Validating MOF files
 
 MathOptFormat files are governed by a schema. Use [JSONSchema.jl](https://github.com/fredo-dedup/JSONSchema.jl)

src/FileFormats/MOF/MOF.jl

@@ -116,7 +116,7 @@ struct Options
     print_compact::Bool
     warn::Bool
     differentiation_backend::MOI.Nonlinear.AbstractAutomaticDifferentiation
-    parse_as_nlpblock::Bool
+    use_nlp_block::Bool
 end
 
 function get_options(m::Model)
@@ -140,19 +140,19 @@ Keyword arguments are:
  - `differentiation_backend::MOI.Nonlinear.AbstractAutomaticDifferentiation = MOI.Nonlinear.SparseReverseMode()`:
    automatic differentiation backend to use when reading models with nonlinear
    constraints and objectives.
- - `parse_as_nlpblock::Bool=true`: if `true` parse `"ScalarNonlinearFunction"`
+ - `use_nlp_block::Bool=true`: if `true` parse `"ScalarNonlinearFunction"`
    into an `MOI.NLPBlock`. If `false`, `"ScalarNonlinearFunction"` are parsed as
    `MOI.ScalarNonlinearFunction` functions.
 """
 function Model(;
     print_compact::Bool = false,
     warn::Bool = false,
     differentiation_backend::MOI.Nonlinear.AbstractAutomaticDifferentiation = MOI.Nonlinear.SparseReverseMode(),
-    parse_as_nlpblock::Bool = true,
+    use_nlp_block::Bool = true,
 )
     model = MOI.Utilities.UniversalFallback(InnerModel{Float64}())
     model.model.ext[:MOF_OPTIONS] =
-        Options(print_compact, warn, differentiation_backend, parse_as_nlpblock)
+        Options(print_compact, warn, differentiation_backend, use_nlp_block)
     return model
 end
 

src/FileFormats/MOF/read.jl

@@ -27,7 +27,7 @@ function Base.read!(io::IO, model::Model)
     read_objective(model, object, name_map)
     read_constraints(model, object, name_map)
     options = get_options(model)
-    if options.parse_as_nlpblock
+    if options.use_nlp_block
         _convert_to_nlpblock(model)
     end
     return

test/FileFormats/MOF/MOF.jl

@@ -749,7 +749,7 @@ minobjective: ScalarNonlinearFunction(exp(x))
 """,
         ["x"],
         String[];
-        parse_as_nlpblock = false,
+        use_nlp_block = false,
     )
 end
 
@@ -761,7 +761,7 @@ c1: ScalarNonlinearFunction(exp(x)^2) <= 1.0
 """,
         ["x"],
         ["c1"];
-        parse_as_nlpblock = false,
+        use_nlp_block = false,
     )
 end