Home Explore Blog Models CI



nix

2nd chunk of `doc/manual/source/language/string-context.md`
5984c4951f04924c7bf96e3f98e4d03cef281a9057f0343b0000000100000df1
    > [`builtins.storePath`] creates a string with a single constant string context element:
    >
    > ```nix
    > builtins.getContext (builtins.storePath "/nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10")
    > ```
    > evaluates to
    > ```nix
    > {
    >   "/nix/store/wkhdf9jinag5750mqlax6z2zbwhqb76n-hello-2.10" = {
    >     path = true;
    >   };
    > }
    > ```


  - [Output string context elements]{#string-context-output}

    > **Example**
    >
    > The behavior of string contexts are best demonstrated with a built-in function that is still experimental: [`builtins.outputOf`].
    > This example will *not* work with stable Nix!
    >
    > ```nix
    > builtins.getContext
    >   (builtins.outputOf
    >     (builtins.storePath "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv")
    >     "out")
    > ```
    > evaluates to
    > ```nix
    > {
    >   "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv" = {
    >     outputs = [ "out" ];
    >   };
    > }
    > ```


- [*derivation deep*]{#string-context-element-derivation-deep}

  *derivation deep* is an advanced feature intended to be used with the
  [`exportReferencesGraph` derivation attribute](./advanced-attributes.html#adv-attr-exportReferencesGraph).
  A *derivation deep* string context element is a derivation path, and refers to both its outputs and the entire build closure of that derivation:
  all its outputs, all the other derivations the given derivation depends on, and all the outputs of those.

  > **Example**
  >
  > The best way to illustrate *derivation deep* string contexts is with [`builtins.addDrvOutputDependencies`].
  > Take a regular constant string context element pointing to a derivation, and transform it into a "Derivation deep" string context element.
  >
  > ```nix
  > builtins.getContext
  >   (builtins.addDrvOutputDependencies
  >     (builtins.storePath "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv"))
  > ```
  > evaluates to
  > ```nix
  > {
  >   "/nix/store/fvchh9cvcr7kdla6n860hshchsba305w-hello-2.12.drv" = {
  >     allOutputs = true;
  >   };
  > }
  > ```


## Inspecting string contexts

Most basically, [`builtins.hasContext`] will tell whether a string has a non-empty context.

When more granular information is needed, [`builtins.getContext`] can be used.
It creates an [attribute set] representing the string context, which can be inspected as usual.


## Clearing string contexts

[`builtins.unsafeDiscardStringContext`](./builtins.md#builtins-unsafeDiscardStringContext) will make a copy of a string, but with an empty string context.
The returned string can be used in more ways, e.g. by operators that require the string context to be empty.
The requirement to explicitly discard the string context in such use cases helps ensure that string context elements are not lost by mistake.
The "unsafe" marker is only there to remind that Nix normally guarantees that dependencies are tracked, whereas the returned string has lost them.

## Constructing string contexts

[`builtins.appendContext`] will create a copy of a string, but with additional string context elements.
The context is specified explicitly by an [attribute set] in the format that [`builtins.hasContext`] produces.
A string with arbitrary contexts can be made like this:

1. Create a string with the desired string context elements.
   (The contents of the string do not matter.)
2. Dump its context with [`builtins.getContext`].
3. Combine it with a base string and repeated [`builtins.appendContext`] calls.


Title: Advanced Nix String Context Elements and Manipulation
Summary
This section delves into further types of Nix string context elements and how to inspect, clear, and construct them. Beyond 'constant' and 'output' elements, the 'derivation deep' type is introduced, which is an advanced feature that refers to a derivation path, all its outputs, and its entire build closure, useful with `exportReferencesGraph`. Examples using `builtins.addDrvOutputDependencies` demonstrate this. For interacting with string contexts, `builtins.hasContext` checks for existence, and `builtins.getContext` retrieves the full context as an attribute set. Strings can be stripped of their context using `builtins.unsafeDiscardStringContext`, which is necessary for certain operations but loses dependency tracking. Finally, `builtins.appendContext` allows for programmatically adding new context elements to a string, enabling the explicit construction of strings with specific contexts.