### ----------------------------------------------------
### -- Gnome::Gio
### -- Licenses: Artistic-2.0
### -- Authors: Marcel Timmerman
### -- File: lib/Gnome/Gio/File.rakumod
### ----------------------------------------------------
### -- Chunk 1 of 6
#TL:1:Gnome::Gio::File:

use v6;
#-------------------------------------------------------------------------------
=begin pod

=head1 Gnome::Gio::File

File and Directory Handling


=head1 Description

B<Gnome::Gio::File> is a high level abstraction for manipulating files on a virtual file system. B<N-GFiles> are lightweight, immutable objects that do no I/O upon creation. It is necessary to understand that B<Gnome::Gio::File> objects do not represent files, merely an identifier for a file.

To construct a B<Gnome::Gio::File>, you can use:
=item C<.new(:path)> if you have a path.
=item C<.new(:uri)> if you have a URI.
=item C<.new(:commandline-arg)> for a command line argument.
=comment item C<g_file_new_tmp()> to create a temporary file from a template.
=comment item C<g_file_parse_name()> from a UTF-8 string gotten from C<g_file_get_parse_name()>.
=comment item C<g_file_new_build_filename()> to create a file from path elements.

One way to think of a B<Gnome::Gio::File> is as an abstraction of a pathname. For normal files the system pathname is what is stored internally, but as B<N-GFiles> are extensible it could also be something else that corresponds to a pathname in a userspace implementation of a filesystem.

Many of the native subroutines originally in this module are not implemented in this Raku class. This is because I/O is very well supported by Raku and there is no need to provide I/O routines here. This class mainly exists to handle returned native objects from other classes. The most important calls needed are thus to get the name of a file or url.


=begin comment
B<N-GFiles> make up hierarchies of directories and files that correspond to the files on a filesystem. You can move through the file system with B<Gnome::Gio::File> using C<g_file_get_parent()> to get an identifier for the parent directory, C<g_file_get_child()> to get a child within a directory, C<g_file_resolve_relative_path()> to resolve a relative path between two B<N-GFiles>. There can be multiple hierarchies, so you may not end up at the same root if you repeatedly call C<g_file_get_parent()> on two different files.

All B<N-GFiles> have a basename (get with C<g_file_get_basename()>). These names are byte strings that are used to identify the file on the filesystem (relative to its parent directory) and there is no guarantees that they have any particular charset encoding or even make any sense at all. If you want to use filenames in a user interface you should use the display name that you can get by requesting the C<G_FILE_ATTRIBUTE_STANDARD_DISPLAY_NAME> attribute with C<g_file_query_info()>. This is guaranteed to be in UTF-8 and can be used in a user interface. But always store the real basename or the B<Gnome::Gio::File> to use to actually access the file, because there is no way to go from a display name to the actual name.

Using B<Gnome::Gio::File> as an identifier has the same weaknesses as using a path in that there may be multiple aliases for the same file. For instance, hard or soft links may cause two different B<N-GFiles> to refer to the same file. Other possible causes for aliases are: case insensitive filesystems, short and long names on FAT/NTFS, or bind mounts in Linux. If you want to check if two B<N-GFiles> point to the same file you can query for the C<G_FILE_ATTRIBUTE_ID_FILE> attribute. Note that B<Gnome::Gio::File> does some trivial canonicalization of pathnames passed in, so that trivial differences in the path string used at creation (duplicated slashes, slash at end of path, "." or ".." path segments, etc) does not create different B<N-GFiles>.

Many B<Gnome::Gio::File> operations have both synchronous and asynchronous versions to suit your application. Asynchronous versions of synchronous functions simply have C<_async()> appended to their function names. The asynchronous I/O functions call a B<GAsyncReadyCallback> which is then used to finalize the operation, producing a GAsyncResult which is then passed to the function's matching C<_finish()> operation.

It is highly recommended to use asynchronous calls when running within a shared main loop, such as in the main thread of an application. This avoids I/O operations blocking other sources on the main loop from being dispatched. Synchronous I/O operations should be performed from worker threads. See the [introduction to asynchronous programming section][async-programming] for more.

Some B<Gnome::Gio::File> operations almost always take a noticeable amount of time, and so do not have synchronous analogs. Notable cases include:
=item C<g_file_mount_mountable()> to mount a mountable file.
=item C<g_file_unmount_mountable_with_operation()> to unmount a mountable file.
=item C<g_file_eject_mountable_with_operation()> to eject a mountable file.


=head2 Entity Tags

One notable feature of B<N-GFiles> are entity tags, or "etags" for short. Entity tags are somewhat like a more abstract version of the traditional mtime, and can be used to quickly determine if the file has been modified from the version on the file system. See the HTTP 1.1 [specification](http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html) for HTTP Etag headers, which are a very similar concept.

=end comment


=begin comment
=head2 See Also

B<Gnome::Gio::FileInfo>, B<Gnome::Gio::FileEnumerator>
=end comment


=head1 Synopsis
=head2 Declaration

  unit class Gnome::Gio::File;
  also is Gnome::N::TopLevelClassSupport;


=head2 Note

B<Gnome::Gio::File> is defined as an interface in the Gnome libraries and therefore should be defined as a Raku role. However, many Gnome modules return native B<Gnome::Gio::File> objects as if they are class objects. There aren't even Gnome classes using it as an interface. Presumably, it is defined like that so the developer can create classes using the File class as an interface which will not be the case in Raku.


=head2 Note

B<Gnome::Gio::File> has many functions of which a large part will not be made available in Raku. This is because many are about read/write, move and rename which Raku is able to do very nice.


=begin comment
=head2 Inheriting this class

Inheriting is done in a special way in that it needs a call from new() to get the native object created by the class you are inheriting from.

  use Gnome::Gio::File:api<1>;

  unit class MyGuiClass;
  also is Gnome::Gio::File;

  submethod new ( |c ) {
    # let the Gnome::Gio::File class process the options
    self.bless( :GFile, |c);
  }

  submethod BUILD ( ... ) {
    ...
  }

=end comment
=comment head2 Example

=end pod
#-------------------------------------------------------------------------------
use NativeCall;

#use Gnome::N::X:api<1>;
use Gnome::N::NativeLib:api<1>;
use Gnome::N::N-GObject:api<1>;
use Gnome::N::TopLevelClassSupport:api<1>;
use Gnome::N::GlibToRakuTypes:api<1>;

use Gnome::Glib::Error:api<1>;
use Gnome::GObject::Object:api<1>;

#-------------------------------------------------------------------------------
unit class Gnome::Gio::File:auth<github:MARTIMM>:api<1>;
also is Gnome::N::TopLevelClassSupport;

has Gnome::Glib::Error $.last-error;
#-------------------------------------------------------------------------------
=begin pod
=head1 Types

=head2 class N-GFile

Native object to hold a file representation

=end pod

#TODO deprecate N-GFile and make it N-GObject
#TT:1:N-GFile:
class N-GFile
  is repr('CPointer')
  is export
  { }

#-------------------------------------------------------------------------------
=begin pod
=head1 Methods
=head2 new

=head3 :path

Create a new File object using a path to a file.

  multi method new ( Str :$path! )


=head3 :uri

Create a new File object using a uri.

  multi method new ( Str :$uri! )


=head3 :commandline-arg, :cwd

Creates a B<Gnome::Gio::File> with the given argument from the command line. The value of I<arg> can be either a URI, an absolute path or a relative path resolved relative to the current working directory. This operation never fails, but the returned object might not support any I/O operation if I<arg> points to a malformed path.

Note that on Windows, this function expects its argument to be in UTF-8 -- not the system code page. This means that you should not use this function with string from argv as it is passed to C<main()>. C<g-win32-get-command-line()> will return a UTF-8 version of the commandline. B<Gnome::Gio::Application> also uses UTF-8 but C<g-application-command-line-create-file-for-arg()> may be more useful for you there. It is also always possible to use this function with B<Gnome::Gio::OptionContext> arguments of type C<G-OPTION-ARG-FILENAME>.

Optionally a directory relative to the argument can be given in $cwd. Otherwise the working directory of the application is used.

  multi method new ( Str :$commandline-arg!, Str :$cwd? )


=head3 :native-object

Create a File object using a native object from elsewhere. See also B<Gnome::N::TopLevelClassSupport>.

  multi method new ( N-GObject :$native-object! )

=end pod

# TM:0:new():inheriting
#TM:1:new(:path):
#TM:1:new(:uri):
#TM:4:new(:native-object):Gnome::N::TopLevelClassSupport
submethod BUILD ( *%options ) {

  # prevent creating wrong native-objects
  if self.^name eq 'Gnome::Gio::File' #`{{ or %options<GFile> }} {

    $!last-error .= new(:native-object(N-GError));

    # check if native object is set by a parent class
    if self.is-valid { }

    # process all options

    # check if common options are handled by some parent
    elsif %options<native-object>:exists { }

    else {
      my $no;

      if ? %options<path> {
        $no = _g_file_new_for_path(%options<path>);
      }

      elsif ? %options<uri> {
        $no = _g_file_new_for_uri(%options<uri>);
      }

      elsif ? %options<commandline-arg> {
        if ? %options<cwd> {
          $no = _g_file_new_for_commandline_arg_and_cwd(
            %options<commandline-arg>, %options<cwd>
          );
        }

        else {
          $no = _g_file_new_for_commandline_arg(%options<commandline-arg>);
        }
      }

      # check if there are unknown options
      elsif %options.elems {
        die X::Gnome.new(
          :message(
            'Unsupported, undefined, incomplete or wrongly typed options for ' ~
            self.^name ~ ': ' ~ %options.keys.join(', ')
          )
        );
      }

      ##`{{ when there are no defaults use this
      # check if there are any options
      elsif %options.elems == 0 {
        die X::Gnome.new(:message('No options specified ' ~ self.^name));
      }
      #}}

      #`{{ when there are options use this instead
      # create default object
      else {
        self._set-native-object(g_file_new());
      }
      }}

      self._set-native-object($no);
    }

    # only after creating the native-object, the gtype is known
    self._set-class-info('GFile');
  }
}

#-------------------------------------------------------------------------------
# no pod. user does not have to know about it.
method _fallback ( $native-sub is copy --> Callable ) {

  my Str $new-patt = $native-sub.subst( '_', '-', :g);

  my Callable $s;
  try { $s = &::("g_file_$native-sub"); };
  if ?$s {
    Gnome::N::deprecate(
      "gtk_application_$native-sub", $new-patt, '0.10.8', '0.11.0'
    );
  }

  else {
    # TODO; check for gtk_, gdk_, g_, pango_, cairo_ !!!
    try { $s = &::("gtk_$native-sub"); } unless ?$s;
    if ?$s {
      Gnome::N::deprecate(
        "gtk_$native-sub", $new-patt.subst('application-'),
        '0.10.8', '0.11.0'
      );
    }

    else {
      try { $s = &::($native-sub); } if !$s and $native-sub ~~ m/^ 'gtk_' /;
      if ?$s {
        Gnome::N::deprecate(
          "$native-sub", $new-patt.subst('gtk-application-'),
          '0.10.8', '0.11.0'
        );
      }
    }
  }

  self._set-class-name-of-sub('GFile');
  $s = callsame unless ?$s;

  $s;
}

#-------------------------------------------------------------------------------
method native-object-ref ( $n-native-object --> N-GFile ) {
  $n-native-object
}

#-------------------------------------------------------------------------------
method native-object-unref ( $n-native-object ) {
  _g_object_unref($n-native-object)
}

#-------------------------------------------------------------------------------
#TM:1:_g_object_unref:
#`{{
=begin pod
=head2 [g_] object_unref

Decreases the reference count of the native object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

=begin comment
If the pointer to the native object may be reused in future (for example, if it is an instance variable of another object), it is recommended to clear the pointer to C<Any> rather than retain a dangling pointer to a potentially invalid I<N-GFile> instance. Use C<g_clear_object()> for this.
=end comment

  method g_object_unref ( N-GFile $object )

=item $object; a I<N-GFile>

=end pod

sub g_object_unref ( N-GFile $object is copy ) {

  #$object = g_object_ref_sink($object) if g_object_is_floating($object);
  _g_object_unref($object)
}
}}

# reason for File to use Object. Inheritance is not needed because there are no
# signals to process.
sub _g_object_unref ( N-GFile $object )
  is native(&gobject-lib)
  is symbol('g_object_unref')
  { * }


#`{{
#-------------------------------------------------------------------------------
# TM:0:append-to:
=begin pod
=head2 append-to

Gets an output stream for appending data to the file. If the file doesn't already exist it is created.

By default files created are generally readable by everyone, but if you pass B<Gnome::Gio::-FILE-CREATE-PRIVATE> in I<flags> the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If I<cancellable> is not C<undefined>, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error C<G-IO-ERROR-CANCELLED> will be returned.

Some file systems don't allow all file names, and may return an C<G-IO-ERROR-INVALID-FILENAME> error. If the file is a directory the C<G-IO-ERROR-IS-DIRECTORY> error will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Returns: a B<Gnome::Gio::FileOutputStream>, or C<undefined> on error. Free the returned object with C<clear-object()>.

  method append-to ( UInt $flags, GCancellable $cancellable, N-GError $error --> GFileOutputStream )

=item $flags; a set of B<UInt>
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $error; a B<Gnome::Gio::Error>, or C<undefined>
=end pod

method append-to ( UInt $flags, GCancellable $cancellable, $error is copy --> GFileOutputStream ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_append_to(
    self._get-native-object-no-reffing, $flags, $cancellable, $error
  )
}

sub g_file_append_to (
  N-GFile $file, GFlag $flags, GCancellable $cancellable, N-GError $error --> GFileOutputStream
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:append-to-async:
=begin pod
=head2 append-to-async

Asynchronously opens I<file> for appending.

For more details, see C<append-to()> which is the synchronous version of this call.

When the operation is finished, I<callback> will be called. You can then call C<g-file-append-to-finish()> to get the result of the operation.

  method append-to-async ( UInt $flags, Int() $io_priority, GCancellable $cancellable, GAsyncReadyCallback $callback, Pointer $user_data )

=item $flags; a set of B<Gnome::Gio::FileCreateFlags>
=item $io_priority; the [I/O priority][io-priority] of the request
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $callback; (scope async): a B<Gnome::Gio::AsyncReadyCallback> to call when the request is satisfied
=item $user_data; (closure): the data to pass to callback function
=end pod

method append-to-async ( UInt $flags, Int() $io_priority, GCancellable $cancellable, GAsyncReadyCallback $callback, Pointer $user_data ) {

  g_file_append_to_async(
    self._get-native-object-no-reffing, $flags, $io_priority, $cancellable, $callback, $user_data
  );
}

sub g_file_append_to_async (
  N-GFile $file, GFlag $flags, int $io_priority, GCancellable $cancellable, GAsyncReadyCallback $callback, gpointer $user_data
) is native(&gio-lib)
  { * }
}}

#`{{
#-------------------------------------------------------------------------------
# TM:0:append-to-finish:
=begin pod
=head2 append-to-finish

Finishes an asynchronous file append operation started with C<append-to-async()>.

Returns: a valid B<Gnome::Gio::FileOutputStream> or C<undefined> on error. Free the returned object with C<clear-object()>.

  method append-to-finish ( GAsyncResult $res, N-GError $error --> GFileOutputStream )

=item $res; B<Gnome::Gio::AsyncResult>
=item $error; a B<Gnome::Gio::Error>, or C<undefined>
=end pod

method append-to-finish ( GAsyncResult $res, $error is copy --> GFileOutputStream ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_append_to_finish(
    self._get-native-object-no-reffing, $res, $error
  )
}

sub g_file_append_to_finish (
  N-GFile $file, GAsyncResult $res, N-GError $error --> GFileOutputStream
) is native(&gio-lib)
  { * }
}}

#`{{
#-------------------------------------------------------------------------------
# TM:0:copy:
=begin pod
=head2 copy

Copies the file I<source> to the location specified by I<destination>. Can not handle recursive copies of directories.

If the flag B<Gnome::Gio::-FILE-COPY-OVERWRITE> is specified an already existing I<destination> file is overwritten.

If the flag B<Gnome::Gio::-FILE-COPY-NOFOLLOW-SYMLINKS> is specified then symlinks will be copied as symlinks, otherwise the target of the I<source> symlink will be copied.

If the flag B<Gnome::Gio::-FILE-COPY-ALL-METADATA> is specified then all the metadata that is possible to copy is copied, not just the default subset (which, for instance, does not include the owner, see B<Gnome::Gio::FileInfo>).

If I<cancellable> is not C<undefined>, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error C<G-IO-ERROR-CANCELLED> will be returned.

If I<progress-callback> is not C<undefined>, then the operation can be monitored by setting this to a B<Gnome::Gio::FileProgressCallback> function. I<progress-callback-data> will be passed to this function. It is guaranteed that this callback will be called after all data has been transferred with the total number of bytes copied during the operation.

If the I<source> file does not exist, then the C<G-IO-ERROR-NOT-FOUND> error is returned, independent on the status of the I<destination>.

If B<Gnome::Gio::-FILE-COPY-OVERWRITE> is not specified and the target exists, then the error C<G-IO-ERROR-EXISTS> is returned.

If trying to overwrite a file over a directory, the C<G-IO-ERROR-IS-DIRECTORY> error is returned. If trying to overwrite a directory with a directory the C<G-IO-ERROR-WOULD-MERGE> error is returned.

If the source is a directory and the target does not exist, or B<Gnome::Gio::-FILE-COPY-OVERWRITE> is specified and the target is a file, then the C<G-IO-ERROR-WOULD-RECURSE> error is returned.

If you are interested in copying the B<Gnome::Gio::File> object itself (not the on-disk file), see C<dup()>.

Returns: C<True> on success, C<False> otherwise.

  method copy ( N-GFile $destination, UInt $flags, GCancellable $cancellable, GFileProgressCallback $progress_callback, Pointer $progress_callback_data, N-GError $error --> Bool )

=item $destination; destination B<Gnome::Gio::File>
=item $flags; set of B<Gnome::Gio::FileCopyFlags>
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $progress_callback;  (scope call): function to callback with progress information, or C<undefined> if progress information is not needed
=item $progress_callback_data; (closure): user data to pass to I<progress-callback>
=item $error; B<Gnome::Gio::Error> to set on error, or C<undefined>
=end pod

method copy ( N-GFile $destination, UInt $flags, GCancellable $cancellable, GFileProgressCallback $progress_callback, Pointer $progress_callback_data, $error is copy --> Bool ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_copy(
    self._get-native-object-no-reffing, $destination, $flags, $cancellable, $progress_callback, $progress_callback_data, $error
  ).Bool
}

sub g_file_copy (
  N-GFile $source, N-GFile $destination, GFlag $flags, GCancellable $cancellable, GFileProgressCallback $progress_callback, gpointer $progress_callback_data, N-GError $error --> gboolean
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:copy-async:
=begin pod
=head2 copy-async

Copies the file I<source> to the location specified by I<destination> asynchronously. For details of the behaviour, see C<copy()>.

If I<progress-callback> is not C<undefined>, then that function that will be called just like in C<g-file-copy()>. The callback will run in the default main context of the thread calling C<g-file-copy-async()> — the same context as I<callback> is run in.

When the operation is finished, I<callback> will be called. You can then call C<g-file-copy-finish()> to get the result of the operation.

  method copy-async ( N-GFile $destination, UInt $flags, Int() $io_priority, GCancellable $cancellable, GFileProgressCallback $progress_callback, Pointer $progress_callback_data, GAsyncReadyCallback $callback, Pointer $user_data )

=item $destination; destination B<Gnome::Gio::File>
=item $flags; set of B<Gnome::Gio::FileCopyFlags>
=item $io_priority; the [I/O priority][io-priority] of the request
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $progress_callback;  (scope notified): function to callback with progress information, or C<undefined> if progress information is not needed
=item $progress_callback_data; (closure progress-callback) : user data to pass to I<progress-callback>
=item $callback; (scope async): a B<Gnome::Gio::AsyncReadyCallback> to call when the request is satisfied
=item $user_data; (closure callback): the data to pass to callback function
=end pod

method copy-async ( N-GFile $destination, UInt $flags, Int() $io_priority, GCancellable $cancellable, GFileProgressCallback $progress_callback, Pointer $progress_callback_data, GAsyncReadyCallback $callback, Pointer $user_data ) {

  g_file_copy_async(
    self._get-native-object-no-reffing, $destination, $flags, $io_priority, $cancellable, $progress_callback, $progress_callback_data, $callback, $user_data
  );
}

sub g_file_copy_async (
  N-GFile $source, N-GFile $destination, GFlag $flags, int $io_priority, GCancellable $cancellable, GFileProgressCallback $progress_callback, gpointer $progress_callback_data, GAsyncReadyCallback $callback, gpointer $user_data
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:copy-attributes:
=begin pod
=head2 copy-attributes

Copies the file attributes from I<source> to I<destination>.

Normally only a subset of the file attributes are copied, those that are copies in a normal file copy operation (which for instance does not include e.g. owner). However if B<Gnome::Gio::-FILE-COPY-ALL-METADATA> is specified in I<flags>, then all the metadata that is possible to copy is copied. This is useful when implementing move by copy + delete source.

Returns: C<True> if the attributes were copied successfully, C<False> otherwise.

  method copy-attributes ( N-GFile $destination, UInt $flags, GCancellable $cancellable, N-GError $error --> Bool )

=item $destination; a B<Gnome::Gio::File> to copy attributes to
=item $flags; a set of B<Gnome::Gio::FileCopyFlags>
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $error; a B<Gnome::Gio::Error>, C<undefined> to ignore
=end pod

method copy-attributes ( N-GFile $destination, UInt $flags, GCancellable $cancellable, $error is copy --> Bool ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_copy_attributes(
    self._get-native-object-no-reffing, $destination, $flags, $cancellable, $error
  ).Bool
}

sub g_file_copy_attributes (
  N-GFile $source, N-GFile $destination, GFlag $flags, GCancellable $cancellable, N-GError $error --> gboolean
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:copy-finish:
=begin pod
=head2 copy-finish

Finishes copying the file started with C<copy-async()>.

Returns: a C<True> on success, C<False> on error.

  method copy-finish ( GAsyncResult $res, N-GError $error --> Bool )

=item $res; a B<Gnome::Gio::AsyncResult>
=item $error; a B<Gnome::Gio::Error>, or C<undefined>
=end pod

method copy-finish ( GAsyncResult $res, $error is copy --> Bool ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_copy_finish(
    self._get-native-object-no-reffing, $res, $error
  ).Bool
}

sub g_file_copy_finish (
  N-GFile $file, GAsyncResult $res, N-GError $error --> gboolean
) is native(&gio-lib)
  { * }
}}

#`{{
#-------------------------------------------------------------------------------
# TM:0:create:
=begin pod
=head2 create

Creates a new file and returns an output stream for writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass B<Gnome::Gio::-FILE-CREATE-PRIVATE> in I<flags> the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If I<cancellable> is not C<undefined>, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error C<G-IO-ERROR-CANCELLED> will be returned.

If a file or directory with this name already exists the C<G-IO-ERROR-EXISTS> error will be returned. Some file systems don't allow all file names, and may return an C<G-IO-ERROR-INVALID-FILENAME> error, and if the name is to long C<G-IO-ERROR-FILENAME-TOO-LONG> will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Returns: a B<Gnome::Gio::FileOutputStream> for the newly created file, or C<undefined> on error. Free the returned object with C<clear-object()>.

  method create ( UInt $flags, GCancellable $cancellable, N-GError $error --> GFileOutputStream )

=item $flags; a set of B<Gnome::Gio::FileCreateFlags>
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $error; a B<Gnome::Gio::Error>, or C<undefined>
=end pod

method create ( UInt $flags, GCancellable $cancellable, $error is copy --> GFileOutputStream ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_create(
    self._get-native-object-no-reffing, $flags, $cancellable, $error
  )
}

sub g_file_create (
  N-GFile $file, GFlag $flags, GCancellable $cancellable, N-GError $error --> GFileOutputStream
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:create-async:
=begin pod
=head2 create-async

Asynchronously creates a new file and returns an output stream for writing to it. The file must not already exist.

For more details, see C<create()> which is the synchronous version of this call.

When the operation is finished, I<callback> will be called. You can then call C<g-file-create-finish()> to get the result of the operation.

  method create-async ( UInt $flags, Int() $io_priority, GCancellable $cancellable, GAsyncReadyCallback $callback, Pointer $user_data )

=item $flags; a set of B<Gnome::Gio::FileCreateFlags>
=item $io_priority; the [I/O priority][io-priority] of the request
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $callback; (scope async): a B<Gnome::Gio::AsyncReadyCallback> to call when the request is satisfied
=item $user_data; (closure): the data to pass to callback function
=end pod

method create-async ( UInt $flags, Int() $io_priority, GCancellable $cancellable, GAsyncReadyCallback $callback, Pointer $user_data ) {

  g_file_create_async(
    self._get-native-object-no-reffing, $flags, $io_priority, $cancellable, $callback, $user_data
  );
}

sub g_file_create_async (
  N-GFile $file, GFlag $flags, int $io_priority, GCancellable $cancellable, GAsyncReadyCallback $callback, gpointer $user_data
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:create-finish:
=begin pod
=head2 create-finish

Finishes an asynchronous file create operation started with C<create-async()>.

Returns: a B<Gnome::Gio::FileOutputStream> or C<undefined> on error. Free the returned object with C<clear-object()>.

  method create-finish ( GAsyncResult $res, N-GError $error --> GFileOutputStream )

=item $res; a B<Gnome::Gio::AsyncResult>
=item $error; a B<Gnome::Gio::Error>, or C<undefined>
=end pod

method create-finish ( GAsyncResult $res, $error is copy --> GFileOutputStream ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_create_finish(
    self._get-native-object-no-reffing, $res, $error
  )
}

sub g_file_create_finish (
  N-GFile $file, GAsyncResult $res, N-GError $error --> GFileOutputStream
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:create-readwrite:
=begin pod
=head2 create-readwrite

Creates a new file and returns a stream for reading and writing to it. The file must not already exist.

By default files created are generally readable by everyone, but if you pass B<Gnome::Gio::-FILE-CREATE-PRIVATE> in I<flags> the file will be made readable only to the current user, to the level that is supported on the target filesystem.

If I<cancellable> is not C<undefined>, then the operation can be cancelled by triggering the cancellable object from another thread. If the operation was cancelled, the error C<G-IO-ERROR-CANCELLED> will be returned.

If a file or directory with this name already exists, the C<G-IO-ERROR-EXISTS> error will be returned. Some file systems don't allow all file names, and may return an C<G-IO-ERROR-INVALID-FILENAME> error, and if the name is too long, C<G-IO-ERROR-FILENAME-TOO-LONG> will be returned. Other errors are possible too, and depend on what kind of filesystem the file is on.

Note that in many non-local file cases read and write streams are not supported, so make sure you really need to do read and write streaming, rather than just opening for reading or writing.

Returns: a B<Gnome::Gio::FileIOStream> for the newly created file, or C<undefined> on error. Free the returned object with C<clear-object()>.

  method create-readwrite ( UInt $flags, GCancellable $cancellable, N-GError $error --> GFileIOStream )

=item $flags; a set of B<Gnome::Gio::FileCreateFlags>
=item $cancellable; optional B<Gnome::Gio::Cancellable> object, C<undefined> to ignore
=item $error; return location for a B<Gnome::Gio::Error>, or C<undefined>
=end pod

method create-readwrite ( UInt $flags, GCancellable $cancellable, $error is copy --> GFileIOStream ) {
  $error .= _get-native-object-no-reffing unless $error ~~ N-GError;

  g_file_create_readwrite(
    self._get-native-object-no-reffing, $flags, $cancellable, $error
  )
}

sub g_file_create_readwrite (
  N-GFile $file, GFlag $flags, GCancellable $cancellable, N-GError $error --> GFileIOStream
) is native(&gio-lib)
  { * }

#-------------------------------------------------------------------------------
# TM:0:create-readwrite-async:
=begin pod
=head2 create-readwrite-async

Asynchronously creates a new file and returns a stream for reading and writing to it. The file must not already exist.

For more details, see C<create-readwrite()> which is the synchronous version of this call.

When the operation is finished, I<callback> will be called. You can then call C<g-file-create-readwrite-finish()> to get the result of the operation.

  method create-readwrite-async ( UInt $flags, Int() $io_priority, GCancellable $cancellable, GAsyncReadyCallback $callback, Pointer $user_data )

=item $flags; a set of B<Gnome::Gio::FileCreateFlags>
=item $io_priority; the [I/O priority][io-priority] of the request
=item $