main.rb in ffi-libfuse-0.4.0

- old
+ new

@@ -22,19 +22,17 @@
           args.concat(extra_args)
         end
 
         # Main function of FUSE
         #
-        # This function:
-        #
         # - parses command line options - see {fuse_parse_cmdline}
-        #   exiting immediately if help or version options were processed
-        # - calls {#fuse_debug}, {#fuse_options}, {#fuse_configure} if implemented by operations
-        # - installs signal handlers for INT, HUP, TERM to unmount and exit filesystem
-        # - installs custom signal handlers if operations implements {fuse_traps}
-        # - creates a fuse handle mounted with registered operations - see {fuse_create}
-        # - calls either the single-threaded (option -s) or the multi-threaded event loop - see {FuseCommon#run}
+        # - calls {#fuse_configure} if implemented by operations
+        # - creates a fuse handle see {fuse_create}
+        # - returns 0 if help or version options were processed (ie after all messages have been printed by libfuse)
+        # - returns 2 if fuse handle is not successfully mounted
+        # - calls {#fuse_traps} if implemented by operations
+        # - calls run on the fuse handle with options from previous steps- see {FuseCommon#run}
         #
         # @param [Array<String>] argv mount.fuse arguments
         #   expects progname, mountpoint, options....
         # @param [FuseArgs|Array<String>] args
         #   alternatively constructed args
@@ -44,37 +42,36 @@
         #  any data to be made available to the {FuseOperations#init} callback
         #
         # @return [Integer] suitable for process exit code
         def fuse_main(*argv, operations:, args: argv.any? ? argv : default_args, private_data: nil)
           run_args = fuse_parse_cmdline(args: args, handler: operations)
-          return 2 unless run_args
 
           fuse_args = run_args.delete(:args)
           mountpoint = run_args.delete(:mountpoint)
 
-          return 3 unless fuse_configure(operations: operations, **run_args)
+          show_only = run_args[:show_help] || run_args[:show_version]
 
+          return 3 if !show_only && !fuse_configure(operations)
+
           warn "FuseCreate: mountpoint: #{mountpoint}, args: [#{fuse_args.argv.join(' ')}]" if run_args[:debug]
           warn "FuseRun: #{run_args}" if run_args[:debug]
 
           fuse = fuse_create(mountpoint, args: fuse_args, operations: operations, private_data: private_data)
 
-          return 0 if run_args[:show_help] || run_args[:show_version]
+          return 0 if show_only
           return 2 if !fuse || !mountpoint
 
-          return unless fuse
-
+          run_args[:traps] = operations.fuse_traps if operations.respond_to?(:fuse_traps)
           fuse.run(**run_args)
         end
         alias main fuse_main
 
         # Parse command line arguments
         #
         # - parses standard command line options (-d -s -h -V)
         #   will call {fuse_debug}, {fuse_version}, {fuse_help} if implemented by handler
         # - calls {fuse_options} for custom option processing if implemented by handler
-        # - records signal handlers if operations implements {fuse_traps}
         # - parses standard fuse mount options
         #
         # @param [Array<String>] argv mount.fuse arguments
         #   expects progname, mountpoint, options....
         # @param [FuseArgs] args
@@ -86,40 +83,41 @@
         #   * args [FuseArgs]: remaining fuse_args to pass to {fuse_create}
         #   * show_help [Boolean]: -h or --help
         #   * show_version [Boolean]: -v or --version
         #   * debug [Boolean]: -d
         #   * others are options to pass to {FuseCommon#run}
+        # @return [nil] if args are not parsed successfully
         def fuse_parse_cmdline(*argv, args: argv.any? ? argv : default_args, handler: nil)
           args = fuse_init_args(args)
 
           # Parse args and print cmdline help
           run_args = Fuse.parse_cmdline(args, handler: handler)
-          return nil unless run_args
 
-          return nil if handler.respond_to?(:fuse_options) && !handler.fuse_options(args)
+          handler.fuse_options(args) if handler.respond_to?(:fuse_options)
 
-          run_args[:traps] = handler.fuse_traps if handler.respond_to?(:fuse_traps)
+          parse_run_options(args, run_args)
 
-          return nil unless parse_run_options(args, run_args)
-
           run_args[:args] = args
           run_args
+        rescue Error
+          nil
         end
 
-        # @return [FuseCommon|nil] the mounted filesystem or nil if not mounted
+        # @return [FuseCommon] the mounted filesystem handle
+        # @return [nil] if not mounted (eg due to --help or --version, or an error)
         def fuse_create(mountpoint, *argv, operations:, args: nil, private_data: nil)
           args = fuse_init_args(args || argv)
 
           operations = FuseOperations.new(delegate: operations) unless operations.is_a?(FuseOperations)
 
           fuse = Fuse.new(mountpoint.to_s, args, operations, private_data)
           fuse if fuse.mounted?
         end
 
         # @!visibility private
-        def fuse_configure(operations:, show_help: false, show_version: false, **_)
-          return true unless operations.respond_to?(:fuse_configure) && !show_help && !show_version
+        def fuse_configure(operations)
+          return true unless operations.respond_to?(:fuse_configure)
 
           # Provide sensible values for FuseContext in case this is referenced during configure
           FFI::Libfuse::FuseContext.overrides do
             operations.fuse_configure
             true
@@ -164,19 +162,20 @@
 
       # @!method fuse_options(args)
       #  @abstract
       #  Called to allow filesystem to handle custom options and observe standard mount options #
       #  @param [FuseArgs] args
-      #  @return [Boolean] true if args parsed successfully
+      #  @raise [Error] if there is an error parsing the options
+      #  @return [void]
       #  @see FuseArgs#parse!
       #  @example
       #    OPTIONS = { 'config=' => :config, '-c ' => :config }
       #    def fuse_options(args)
       #       args.parse!(OPTIONS) do |key:, value:, out:, **opts|
       #
       #          # raise errors for invalid config
-      #          raise FFI::Libfuse::FuseArgs::Error, "Invalid config" unless valid_config?(key,value)
+      #          raise FFI::Libfuse::Error, "Invalid config" unless valid_config?(key,value)
       #
       #          # Configure the file system
       #          @config = value if key == :config
       #
       #          #Optionally manipulate other arguments for fuse_mount() based on the current argument and state
@@ -187,19 +186,22 @@
       #       end
       #    end
 
       # @!method fuse_traps
       #  @abstract
+      #  Passed to {FuseCommon#run} to allow filesystem to handle custom signal traps. These traps
+      #  are merged over those from {FuseCommon#default_traps}
       #  @return [Hash<String|Symbol|Integer,String|Proc>]
       #    map of signal name or number to signal handler as per Signal.trap
       #  @example
       #    def fuse_traps
       #      { HUP: ->() { reload() }}
       #    end
 
       # @!method fuse_version
       #  @abstract
+      #  Called as part of generating output for the -V option
       #  @return [String] a custom version string to output with -V option
 
       # @!method fuse_help
       #  @abstract
       #  Called as part of generating output for the -h option
@@ -212,9 +214,10 @@
       #  @return [void]
 
       # @!method fuse_configure
       #  @abstract
       #  Called immediately before the filesystem is mounted, after options have been parsed
+      #  (eg to validate required options)
       #
       #  @raise [Error] to prevent the mount from proceeding
       #  @return [void]
 
       # @!endgroup