doc:
  short_help: Make sure a file/folder has a certain owner/group.
  help: |
    Make sure a file/folder has a certain owner/group.

    This will recursively apply the owner/group change in case the path is a directory.
    If the path does not exist, an empty file will be created.

    Root/sudo permissions will be used to do the chown.

    If the owner/group does not exist on the machine, this will create them before changing the target ownership.
  examples:
  - title: Set group and user attributes on an (existing) file.
    vars:
      path: /tmp/freckles.sh
      owner: freckles
      group: freckles
    desc: |
      If the file ``/tmp/freckles.sh`` exists, this sets its group and owner to 'freckles'. If the file doesn't exist, nothing will be done.

args:
  path:
    doc:
      short_help: the path in question
    type: string
    required: false
  owner:
    doc:
      short_help: the owner of the file/folder
    type: string
    required: false
    cli:
      metavar: USER
  group:
    doc:
      short_help: the group of the file/folder
    type: string
    required: false
    cli:
      metavar: GROUP
  system_user:
    doc:
      short_help: Whether the user and group should be of system user/group type.
    type: boolean
    required: false
    default: false
    cli:
      show_default: true
      is_flag: true
  recursive:
    doc:
      short_help: Whether to apply the changes recursively (if folder).
    required: false
    default: false
    type: boolean

meta:
  tags:
  - filesystem
  - file
  - chown
  - featured-frecklecutable

frecklets:
- group-exists:
    group: '{{:: group ::}}'
    system_group: '{{:: system_user ::}}'
    frecklet::skip: "{{:: group | true_if_empty_or('root') ::}}"
- user-exists:
    name: '{{:: owner ::}}'
    system_user: '{{:: system_user ::}}'
    frecklet::skip: "{{:: owner | true_if_empty_or('root') ::}}"
- task:
    become: true
    register: __f_stat__
  frecklet:
    name: stat
    type: ansible-module
    desc:
      short: "[check stats for '{{:: path ::}}]"
      long: |
        Check stats for path '{{:: path ::}}', save result in internal variable '__f_stat__'.
    properties:
      elevated: true
      idempotent: false
      internet: false
  vars:
    path: '{{:: path ::}}'
- task:
    become: true
    when: __f_stat__.stat.exists and __f_stat__.stat.isdir
  frecklet:
    name: file
    type: ansible-module
    properties:
      elevated: true
      idempotent: true
      internet: false
    desc:
      short: "change ownership of folder '{{:: path ::}}'"
      long: |
        Check internal variable '__f_stat__' to determine whether '{{:: path ::}}' exists and whether it a file or a folder.

        If {{:: path ::}} exists and is a folder (as root{%:: if recursive ::%}, recursively{%:: endif ::%}):

          {%:: if group ::%}- set group to be '{{:: group ::}}'{%:: endif ::%}
          {%:: if owner ::%}- set user to be '{{:: owner ::}}'{%:: endif ::%}
  vars:
    path: '{{:: path ::}}'
    owner: '{{:: owner ::}}'
    group: '{{:: group ::}}'
    recurse: '{{:: recursive ::}}'
    state: directory
- task:
    become: true
    when: __f_stat__.stat.exists and not __f_stat__.stat.isdir
  frecklet:
    name: file
    type: ansible-module
    properties:
      elevated: true
      idempotent: true
      internet: false
    desc:
      msg: "change ownership of file '{{:: path ::}}'"
      desc: |
        Check internal variable '__f_stat__' to determine whether '{{:: path ::}}' exists and whether it a file or a folder.

        If {{:: path ::}} does not exist or is a file (as root):

          - ensure the file exists (create an empty one if necessary).
          {%:: if group ::%}- set group to be '{{:: group ::}}'{%:: endif ::%}
          {%:: if owner ::%}- set user to be '{{:: owner ::}}'{%:: endif ::%}
  vars:
    path: '{{:: path ::}}'
    owner: '{{:: owner ::}}'
    group: '{{:: group ::}}'
    state: file