privacy.sexy/docs/collection-files.md

Collection files

• privacy.sexy is a data-driven application where it reads the necessary OS-specific logic from yaml files in application/collections
• 💡 Best practices
  • If you repeat yourself, try to utilize YAML-defined functions
  • Always try to add documentation and a way to revert a tweak in scripts
• 📖 Types in code: collection.yaml.d.ts

Objects

Collection

• A collection simply defines:
  • different categories and their scripts in a tree structure
  • OS specific details
• Also allows defining common functions to be used throughout the collection if you'd like different scripts to share same code.

Collection syntax

• os: string (required)
  • Operating system that the Collection is written for.
  • 📖 See OperatingSystem.ts enumeration for allowed values.
• actions: [ Category , ... ] (required)
  • Each category is rendered as different cards in card presentation.
  • ❗ A Collection must consist of at least one category.
• functions: [ Function , ... ]
  • Functions are optionally defined to re-use the same code throughout different scripts.
• scripting: ScriptingDefinition (required)
  • Defines the scripting language that the code of other action uses.

Category

• Category has a parent that has tree-like structure where it can have subcategories or subscripts.
• It's a logical grouping of different scripts and other categories.

Category syntax

• category: string (required)
  • Name of the category
  • ❗ Must be unique throughout the Collection
• children: [ Category | Script , ... ] (required)
  • ❗ Category must consist of at least one subcategory or script.
  • Children can be combination of scripts and subcategories.

Script

• Script represents a single tweak.
• A script must include either:
  • A code and revertCode
  • Or call to call YAML-defined functions
• 🙏 For any new script, please add revertCode and docs values if possible.

Script syntax

• name: string (required)
  • Name of the script
  • ❗ Must be unique throughout the Collection
  • E.g. Disable targeted ads
• code: string (may be required)
  • Batch file commands that will be executed
  • 💡 If defined, best practice to also define revertCode
  • ❗ If not defined call must be defined, do not define if call is defined.
• revertCode: string
  • Code that'll undo the change done by code property.
  • E.g. let's say code sets an environment variable as setx POWERSHELL_TELEMETRY_OPTOUT 1
    • then revertCode should be doing setx POWERSHELL_TELEMETRY_OPTOUT 0
  • ❗ Do not define if call is defined.
• call: FunctionCall | [ FunctionCall , ... ] (may be required)
  • A shared function or sequence of functions to call (called in order)
  • ❗ If not defined code must be defined
• docs: string | [string, ... ]
  • Single documentation URL or list of URLs for those who wants to learn more about the script
  • E.g. https://docs.microsoft.com/en-us/windows-server/
• recommend: "standard" | "strict" | undefined (default)
  • If not defined then the script will not be recommended
  • If defined it can be either
    • standard: Only non-breaking scripts without limiting OS functionality
    • strict: Scripts that can break certain functionality in favor of privacy and security

FunctionCall

• Describes a single call to a function by optionally providing values to its parameters.
• 👀 See parameter substitution for an example usage

FunctionCall syntax

• function: string (required)
  • Name of the function to call.
  • ❗ Function with same name must defined in functions property of Collection
• parameters: [ parameterName: parameterValue, ... ]

  • Defines key value dictionary for each parameter and its value

  • E.g.

      parameters:
        userDefinedParameterName: parameterValue
        # ...
        appName: Microsoft.WindowsFeedbackHub
    

Function

• Functions allow re-usable code throughout the defined scripts.
• Functions are templates compiled by privacy.sexy and uses special expressions.
• Functions can call other functions by defining call property instead of code
• 👀 See parameter substitution for an example usage

Expressions

• Expressions are defined inside mustaches (double brackets, {{ and }})
• Expression syntax is inspired by Go Templates

Parameter substitution

A simple function example

  function: EchoArgument
  parameters:
    - name: 'argument'
  code: Hello {{ $argument }} !

It would print "Hello world" if it's called in a script as following:

  script: Echo script
  call:
    function: EchoArgument
    parameters:
      argument: World

A function can call other functions such as:

  - 
    function: CallerFunction
    parameters:
      - name: 'value'
    call:
      function: EchoArgument
      parameters:
        argument: {{ $value }}
  -
    function: EchoArgument
    parameters:
      - name: 'argument'
    code: Hello {{ $argument }} !

with

• Skips the block if the variable is absent or empty.

• Binds its context (.) value of provided argument for the parameter only if its value is provided.

• A block is defined as {{ with $parameterName }} Parameter value is {{ . }} here {{ end }}

• The parameters used for with condition should be declared as optional, otherwise with block becomes redundant.

• Example:

    function: FunctionThatOutputsConditionally
    parameters:
      - name: 'argument'
        optional: true
    code: |- 
      {{ with $argument }}
        $argument's value is: {{ . }}
      {{ end }}
  

Function syntax

• name: string (required)
  • Name of the function that scripts will use.
  • Convention is to use camelCase, and be verbs.
  • E.g. uninstallStoreApp
  • ❗ Function names must be unique
• parameters: [ FunctionParameter , ... ]
  • List of parameters that function code refers to.
  • ❗ Must be defined to be able use in FunctionCall or expressions code: string (required if call is undefined)
  • Batch file commands that will be executed
  • 💡 If defined, best practice to also define revertCode
  • ❗ If not defined call must be defined
• revertCode: string
  • Code that'll undo the change done by code property.
  • E.g. let's say code sets an environment variable as setx POWERSHELL_TELEMETRY_OPTOUT 1
    • then revertCode should be doing setx POWERSHELL_TELEMETRY_OPTOUT 0
• call: FunctionCall | [ FunctionCall , ... ] (may be required)
  • A shared function or sequence of functions to call (called in order)
  • The parameter values that are sent can use expressions
  • ❗ If not defined code must be defined

FunctionParameter

• Defines a parameter that function requires optionally or mandatory.
• Its arguments are provided by a Script through a FunctionCall.

FunctionParameter syntax

• name: string (required)
  • Name of the parameters that the function has.
  • Parameter names must be defined to be used in expressions.
  • ❗ Parameter names must be unique and include alphanumeric characters only.
• optional: boolean (default: false)
  • Specifies whether the caller Script must provide any value for the parameter.
  • If set to false i.e. an argument value is not optional then it expects a non-empty value for the variable;
    • Otherwise it throws.
  • 💡 Set it to true if a parameter is used conditionally;
    • Or else set it to false for verbosity or do not define it as default value is false anyway.
  • 💡 Can be used in conjunction with with expression.

ScriptingDefinition

• Defines global properties for scripting that's used throughout its parent Collection.

ScriptingDefinition syntax

• language: string (required)
  • 📖 See ScriptingLanguage.ts enumeration for allowed values.
• startCode: string (required)
  • Code that'll be inserted on top of user created script.
  • Global variables such as $homepage, $version, $date can be used using parameter substitution code syntax such as Welcome to {{ $homepage }}!
• endCode: string (required)
  • Code that'll be inserted at the end of user created script.
  • Global variables such as $homepage, $version, $date can be used using parameter substitution code syntax such as Welcome to {{ $homepage }}!