Struct nickel_lang_core::program::Program

pub struct Program<EC: EvalCache> {
    pub color_opt: ColorOpt,
    pub field: FieldPath,
    /* private fields */
}

A Nickel program.

Manage a file database, which stores the original source code of the program and eventually the code of imported expressions, and a dictionary which stores corresponding parsed terms.

Fields

color_opt: ColorOpt

The color option to use when reporting errors.

field: FieldPath

A specific field to act on. It is empty by default, which means that the whole program will be evaluated, but it can be set by the user (for example by the --field argument of the CLI) to evaluate only a specific field.

Implementations

impl<EC: EvalCache> Program<EC>

pub fn new_from_stdin(trace: impl Write + 'static) -> Result<Self>

Create a program by reading it from the standard input.

pub fn new_from_files<I, P>( paths: I, trace: impl Write + 'static ) -> Result<Self>

where I: IntoIterator<Item = P>, P: Into<OsString>,

Create program from possibly multiple files. Each input path is turned into a Term::Import and the main program will be the BinaryOp::Merge of all the inputs.

pub fn new_from_file( path: impl Into<OsString>, trace: impl Write + 'static ) -> Result<Self>

pub fn new_from_source<T, S>( source: T, source_name: S, trace: impl Write + 'static ) -> Result<Self>

where T: Read, S: Into<OsString> + Clone,

Create a program by reading it from a generic source.

pub fn parse_override( &mut self, assignment: String, priority: MergePriority ) -> Result<FieldOverride, ParseError>

Parse an assignment of the form path.to_field=value as an override, with the provided merge priority. Assignments are typically provided by the user on the command line, as part of the customize mode.

This method simply calls FieldOverride::parse with the crate::cache::Cache of the current program.

pub fn parse_field_path( &mut self, path: String ) -> Result<FieldPath, ParseError>

Parse a dot-separated field path of the form path.to.field.

This method simply calls FieldPath::parse with the crate::cache::Cache of the current program.

pub fn add_overrides( &mut self, overrides: impl IntoIterator<Item = FieldOverride> )

pub fn add_import_paths<P>(&mut self, paths: impl Iterator<Item = P>)

where PathBuf: From<P>,

Adds import paths to the end of the list.

pub fn parse(&mut self) -> Result<RichTerm, Error>

Only parse the program, don’t typecheck or evaluate. returns the RichTerm AST

pub fn eval(&mut self) -> Result<RichTerm, Error>

Parse if necessary, typecheck and then evaluate the program.

pub fn eval_full(&mut self) -> Result<RichTerm, Error>

Same as eval, but proceeds to a full evaluation.

pub fn eval_full_for_export(&mut self) -> Result<RichTerm, Error>

Same as eval, but proceeds to a full evaluation. Optionally take a set of overrides that are to be applied to the term (in practice, to be merged with).

Skips record fields marked not_exported.

Arguments

• override is a list of overrides in the form of an iterator of FieldOverrides. Each override is imported in a separate in-memory source, for complete isolation (this way, overrides can’t accidentally or intentionally capture other fields of the configuration). A stub record is then built, which has all fields defined by overrides, and values are an import referring to the corresponding isolated value. This stub is finally merged with the current program before being evaluated for import.

pub fn eval_deep(&mut self) -> Result<RichTerm, Error>

Same as eval_full, but does not substitute all variables.

pub fn query(&mut self) -> Result<Field, Error>

Prepare for evaluation, then fetch the metadata of self.field, or list the fields of the whole program if self.field is empty.

pub fn typecheck(&mut self) -> Result<(), Error>

Load, parse, and typecheck the program and the standard library, if not already done.

pub fn report<E>(&mut self, error: E, format: ErrorFormat)

where E: IntoDiagnostics<FileId>,

Wrapper for report.

pub fn report_as_str<E>(&mut self, error: E) -> String

where E: IntoDiagnostics<FileId>,

Build an error report as a string and return it.

pub fn eval_record_spine(&mut self) -> Result<RichTerm, Error>

Evaluate a program into a record spine, a form suitable for extracting the general structure of a configuration, and in particular its interface (fields that might need to be filled).

This form is used to extract documentation through nickel doc, for example.

Record spine

By record spine, we mean that the result is a tree of evaluated nested records, and leafs are either non-record values in WHNF or partial expressions left unevaluated¹. For example, the record spine of:

{
  foo = {bar = 1 + 1} & {baz.subbaz = [some_func "some_arg"] @ ["snd" ++ "_elt"]},
  input,
  depdt = input & {extension = 2},
}

is

{
  foo = {
    bar = 2,
    baz = {
      subbaz = [some_func "some_arg", "snd" ++ "_elt"],
    },
  },
  input,
  depdt = input & {extension = 2},
}

To evaluate a term to a record spine, we first evaluate it to a WHNF and then:

• If the result is a record, we recursively evaluate subfields to record spines
• If the result isn’t a record, it is returned as it is
• If the evaluation fails with crate::error::EvalError::MissingFieldDef, the original term is returned unevaluated¹
• If any other error occurs, the evaluation fails and returns the error.

---

1. Because we want to handle partial configurations as well, crate::error::EvalError::MissingFieldDef errors are ignored: if this is encountered when evaluating a field, this field is just left as it is and the evaluation proceeds. ↩

pub fn extract_doc(&mut self) -> Result<ExtractedDocumentation, Error>

Extract documentation from the program

pub fn set_skip_stdlib(&mut self)

pub fn pprint_ast( &mut self, out: &mut impl Write, apply_transforms: bool ) -> Result<(), Error>