wineole 0.1.0 → 0.2.0

data/lib/wineole/msoffice/vba.rb

@@ -0,0 +1,199 @@
+require 'English'
+require_relative '../errors'
+
+module WineOLE
+  module MSOffice
+    # Programmatic access to a workbook's VBA project is off by default, and
+    # turning it on means writing a macro security setting in the registry.
+    # This module can read and write it -- but nothing in the wrapper calls
+    # the writing half. That is for `wineole-vba`, which a human runs, and
+    # for tests, which need to exercise both sides of the switch.
+    module VBA
+      class Error < WineOLE::Error; end
+      class AccessDenied < Error; end
+
+      ACCESS_KEY = 'HKCU\Software\Microsoft\Office\11.0\Excel\Security'.freeze
+      ACCESS_VALUE = 'AccessVBOM'.freeze
+      CODEPAGE_KEY = 'HKLM\System\CurrentControlSet\Control\Nls\CodePage'.freeze
+
+      # :enabled, :disabled, or :unset when the value is not there at all.
+      def self.state
+        raw = read(ACCESS_KEY, ACCESS_VALUE)
+        return :unset if raw.nil?
+
+        raw.to_i(16).zero? ? :disabled : :enabled
+      end
+
+      def self.enabled?
+        state == :enabled
+      end
+
+      # Touching VBProject when access is refused gives 0x800A03EC and a
+      # localized message -- the same HRESULT a rejected NumberFormat
+      # gives, and neither identifies the condition. The registry is what
+      # turns the refusal into advice.
+      def self.denied!
+        message =
+          case state
+          when :enabled
+            'access to the VBA project was refused even though the registry ' \
+            'has it enabled -- Excel reads that setting when it starts, so ' \
+            'restart Excel if it was switched on while this instance was running'
+          else
+            'access to the VBA project is disabled. Run `wineole-vba enable`, ' \
+            'then restart Excel -- it reads the setting at startup'
+          end
+        raise AccessDenied, message
+      end
+
+      def self.enable!
+        write(ACCESS_KEY, ACCESS_VALUE, '1')
+      end
+
+      def self.disable!
+        write(ACCESS_KEY, ACCESS_VALUE, '0')
+      end
+
+      # The Windows ANSI codepage of this prefix, as a name Ruby knows.
+      # Never hardcoded: VBA source files are written and read in whatever
+      # this is, and it is not CP932 everywhere.
+      #
+      # Memoized because it costs a `wine reg` subprocess -- measured at
+      # 328 ms on this host -- and a machine's ANSI codepage does not change
+      # while a process runs. Without this an import pays it twice and a
+      # non-ASCII refusal pays it three times.
+      def self.codepage
+        @codepage ||= read_codepage
+      end
+
+      # For tests, which swap the codepage to exercise both sides of it.
+      def self.forget_codepage
+        @codepage = nil
+      end
+
+      def self.read_codepage
+        raw = read(CODEPAGE_KEY, 'ACP')
+        raise Error, "could not read the ANSI codepage (ACP) from #{CODEPAGE_KEY}" if raw.nil?
+
+        name = "CP#{raw}"
+        begin
+          ::Encoding.find(name)
+        rescue ArgumentError
+          raise Error, "the registry reports ANSI codepage #{raw.inspect}, which Ruby does not know"
+        end
+        name
+      end
+
+      # One explanation, used by both paths that hand text to Excel. They
+      # are bound by the same codepage and fail the same way, so the caller
+      # should not be able to tell from the message which one they hit --
+      # only which character stopped it.
+      #
+      # `where` says what the text was, because the way out differs: code
+      # given as a string can be rewritten with ChrW(), a file has to be
+      # edited.
+      def self.unrepresentable!(char, where)
+        raise ArgumentError,
+          "#{where} contains #{char.inspect}, which the system codepage (#{codepage}) " \
+          "cannot represent. Excel stores a module's text in that codepage, so the " \
+          'character would be silently replaced rather than stored. Rewrite it with ' \
+          'Chr()/ChrW() escapes, which are built at run time and are not bound by the ' \
+          'codepage the source text is'
+      end
+
+      # BOMs, longest first -- FF FE 00 00 is UTF-32LE and also starts with
+      # the UTF-16LE BOM, so a shorter match must never be tried first.
+      BOMS = [
+        ["\x00\x00\xFE\xFF".b, 'UTF-32BE'],
+        ["\xFF\xFE\x00\x00".b, 'UTF-32LE'],
+        ["\xEF\xBB\xBF".b,      'UTF-8'],
+        ["\xFE\xFF".b,           'UTF-16BE'],
+        ["\xFF\xFE".b,           'UTF-16LE']
+      ].freeze
+
+      # What encoding a VBA source file should be read as. Three rules, and
+      # every one of them decides on evidence rather than on a guess -- an
+      # encoding a heuristic merely finds likely is exactly the "succeeded,
+      # returned a value, the value is wrong" failure this wrapper exists to
+      # remove.
+      #
+      #   1. A BOM is conclusive. Follow it.
+      #   2. Bytes that are not valid UTF-8 PROVE the file is not UTF-8, so
+      #      read it as the ANSI codepage -- which is what Excel's own
+      #      Export writes, and what every .bas from a Windows toolchain is.
+      #   3. Otherwise UTF-8.
+      #
+      # Rule 2 is the one that earns its place, and the direction matters:
+      # measured on this host, a CP932 file read as UTF-8 is invalid 95.07%
+      # of the time at ONE non-ASCII character and 99.99% by five, so real
+      # codepage files land here almost without exception. The reverse does
+      # not hold -- UTF-8 bytes read as CP932 come out VALID from two
+      # characters on, silently wrong. That asymmetry is why UTF-8 is the
+      # fallback in rule 3 and the codepage is never the default: guessing
+      # UTF-8 and being wrong is loud, guessing the codepage and being wrong
+      # is silent.
+      #
+      # What is left is a file in the codepage whose bytes happen to be
+      # valid UTF-8 -- undecidable, by construction, for anyone. Pass
+      # `encoding:` to skip all of this when you already know.
+      def self.detect_encoding(path)
+        head = ::File.binread(path, 4).to_s
+        BOMS.each { |bytes, name| return name if head.start_with?(bytes) }
+
+        ::File.binread(path).force_encoding('UTF-8').valid_encoding? ? 'UTF-8' : codepage
+      end
+
+      def self.read(key, value)
+        out, ok = run_reg(['query', key, '/v', value])
+        return nil unless ok
+
+        # "    NAME    TYPE    VALUE", indented, and wine leaves a CR on the
+        # end. Stripping each line before splitting is what makes both go
+        # away: without it the leading spaces produce an empty first field
+        # and the value comes back as "REG_SZ    932\r\n".
+        #
+        # The name is matched as a whole field, not as a substring of the
+        # line -- otherwise a value name that happens to appear inside
+        # another value's data would match, and it would happen silently.
+        matches = out.lines.filter_map do |l|
+          parts = l.strip.split(/\s+/, 3)
+          parts if parts.length == 3 && parts[0] == value
+        end
+
+        if matches.length > 1
+          raise Error,
+                "found #{matches.length} lines naming #{value} in `wine reg query #{key}` " \
+                "output, expected exactly one: #{out.inspect}"
+        end
+
+        if matches.empty?
+          raise Error,
+                "the command succeeded but no line naming #{value} could be parsed from " \
+                "`wine reg query #{key}` output: #{out.inspect}"
+        end
+
+        matches.first[2]
+      end
+      private_class_method :read
+
+      def self.write(key, value, data)
+        _out, ok = run_reg(['add', key, '/v', value, '/t', 'REG_DWORD', '/d', data, '/f'])
+        ok
+      end
+      private_class_method :write
+
+      # The only place that shells out, and deliberately not private: it is
+      # the seam the tests replace so that no test touches a real registry.
+      #
+      # Exit status is the only trustworthy signal. `reg` writes both its
+      # success message and its not-found message to stdout, in the system
+      # language, and wine writes unrelated `fixme:` lines to stderr.
+      def self.run_reg(args)
+        out = IO.popen(['wine', 'reg', *args], err: File::NULL, &:read)
+        [out.to_s, $CHILD_STATUS&.success? || false]
+      rescue SystemCallError, IOError
+        ['', false]
+      end
+    end
+  end
+end

data/lib/wineole/msoffice/vba_api.rb

@@ -0,0 +1,366 @@
+require 'tmpdir'
+require_relative 'paths'
+require_relative 'vba'
+require_relative 'vba_block'
+
+module WineOLE
+  module MSOffice
+    # The VBA surface of a workbook, reached as `book.vba`.
+    #
+    # TWO GRANULARITIES LIVE HERE and the names are what keep them apart.
+    # `write` and `remove` act on a named BLOCK inside a module -- the span
+    # this wrapper owns, delimited by sentinel comments, which may sit in a
+    # module full of code somebody else wrote. `add_component`,
+    # `remove_component`, `import` and `export` act on whole COMPONENTS.
+    #
+    # The verbs are not interchangeable either, and the difference is
+    # deliberate. `write` is an upsert: writing the same name again replaces
+    # that block, so it is idempotent. `add_component` is create-only and
+    # refuses a name that is already taken -- "overwriting" a component
+    # would destroy whatever a person put in it, so there is no way to ask
+    # for that.
+    #
+    # WHERE CODE GOES DECIDES WHETHER IT CAN BE CALLED. Measured against a
+    # live Excel 11:
+    #
+    #   standard module   Run("Name") works and returns the value;
+    #                     a worksheet formula =Name() works too.
+    #                     Private does NOT hide it from either.
+    #   ThisWorkbook,     Run("Name") fails ("macro not found"). Run with
+    #   a worksheet,      the module qualified -- Run("Sheet1.Name") --
+    #   a UserForm        runs it but hands back nil, so a Function's
+    #                     return value cannot be collected. =Name() is
+    #                     #NAME?.
+    #
+    # So code meant to be called belongs in a standard module (which is
+    # where `into: nil` puts it), and code in a sheet or ThisWorkbook module
+    # is there to be reached by Excel itself -- an ActiveX control's
+    # `_Click`, a workbook event.
+    class BookVBA
+      # The module this wrapper makes for itself when `into:` is not given.
+      DEFAULT_MODULE = 'WineOLE'.freeze
+
+      # VBComponents.Add's type argument. 100 (a Document module -- a
+      # worksheet or ThisWorkbook) is deliberately absent: Excel owns those
+      # and neither creates nor destroys them on request.
+      KINDS = { standard: 1, class: 2, form: 3 }.freeze
+
+      # The Type of a component Excel owns. Cannot be added, cannot be
+      # removed -- only emptied.
+      DOCUMENT_TYPE = 100
+
+      def initialize(ole, convert_paths:)
+        @ole = ole
+        @convert_paths = convert_paths
+      end
+
+      # Put a named block of VBA into this workbook.
+      #
+      # `into:` names an EXISTING component -- a UserForm, ThisWorkbook, a
+      # worksheet's module, a module made with #add_component. It is not
+      # created on demand: a typo would otherwise become a new module in
+      # silence. Without it the block goes in this wrapper's own module,
+      # which is created on demand because its name is not the caller's to
+      # get wrong.
+      #
+      # The block is what this wrapper owns -- writing the same name again
+      # replaces it, and nothing else in the module is touched. That matters
+      # because the module may hold code somebody wrote by hand.
+      def write(code, name: 'main', into: nil)
+        VBABlock.write(target_module(into), name, code)
+        self
+      end
+
+      # Remove a named block. When `from:` is given, only the block is
+      # removed -- a component the caller named is the caller's, never swept
+      # up here (a UserForm can be deleted, unlike ThisWorkbook, so this has
+      # to be a rule rather than an accident of what COM allows). Use
+      # #remove_component to delete one deliberately.
+      #
+      # Without `from:`, this wrapper's own module is the target, and when
+      # it has nothing but whitespace left the module goes too -- an empty
+      # module is litter, and that one IS ours to clean up.
+      #
+      # VBABlock.remove already fetched the whole body to find the block; it
+      # hands back the remaining lines so this does not have to fetch the
+      # body a second time just to ask whether it is empty.
+      def remove(name, from: nil)
+        if from
+          VBABlock.remove(named_component!(from).CodeModule, name)
+          return self
+        end
+
+        component = existing_component(DEFAULT_MODULE)
+        return self if component.nil?
+
+        remaining = VBABlock.remove(component.CodeModule, name)
+        project.VBComponents.Remove(component) if remaining && VBABlock.blank_lines?(remaining)
+        self
+      end
+
+      # Create an empty component. Create-only on purpose: see the class
+      # comment on why there is no "overwrite a component".
+      #
+      # The existence check has to come BEFORE Add, not after, and that is
+      # measured rather than defensive: Add and the rename that follows it
+      # are not atomic. Adding under a taken name SUCCEEDS, and only the
+      # rename fails (0x80020009), leaving a stray `Module1` behind that
+      # nobody asked for. Checking first is what keeps the failure clean.
+      def add_component(name, kind: :standard)
+        type = KINDS[kind]
+        unless type
+          raise ArgumentError,
+            "unknown component kind #{kind.inspect} -- expected one of #{KINDS.keys.inspect}. " \
+            'A worksheet module and ThisWorkbook are not on that list because Excel ' \
+            'owns them; they exist already and cannot be made'
+        end
+
+        if existing_component(name)
+          raise ArgumentError,
+            "this workbook already has a VBA component named #{name.inspect}. " \
+            'add_component never overwrites one -- that would destroy whatever is ' \
+            'in it. Remove it first, or use write(into:) to put a block inside it'
+        end
+
+        component = project.VBComponents.Add(type)
+        begin
+          component.Name = name
+        rescue WineOLE::RemoteError
+          # Add succeeded and the rename did not, so the component exists
+          # under a name nobody chose. Take it back out rather than leaving
+          # the litter the pre-check exists to prevent.
+          project.VBComponents.Remove(component)
+          raise ArgumentError,
+            "Excel refused #{name.inspect} as a component name. VBA names start with a " \
+            'letter and hold letters, digits and underscores, up to 31 characters'
+        end
+        component
+      end
+
+      # Delete a component outright, with whatever is inside it.
+      def remove_component(name)
+        component = named_component!(name)
+        if component.Type == DOCUMENT_TYPE
+          raise ArgumentError,
+            "#{name.inspect} is a module Excel owns (a worksheet's, or ThisWorkbook's) " \
+            'and cannot be deleted -- it exists for as long as the sheet or the workbook ' \
+            'does. To take this wrapper\'s code back out of it, use remove(name, from:)'
+        end
+
+        project.VBComponents.Remove(component)
+        self
+      end
+
+      # Read a VBA source file on this machine into the project as a new
+      # component. Excel's own Import does the work, so the component's name
+      # and kind come from the file.
+      #
+      # `encoding:` skips the detection when the caller already knows; the
+      # rules the default follows are on VBA.detect_encoding.
+      def import(path, encoding: nil)
+        local_bridge!('import')
+        reject_dotdot!(path)
+        source = encoding || VBA.detect_encoding(path)
+        text = decode(::File.binread(path), source, path, guessed: encoding.nil?)
+
+        Dir.mktmpdir('wineole-vba') do |dir|
+          staged = ::File.join(dir, ::File.basename(path))
+          ::File.binwrite(staged, to_codepage(text, path))
+          project.VBComponents.Import(Paths.to_wine(staged))
+        end
+        self
+      end
+
+      # Write a component out as a file on this machine, in UTF-8 with LF --
+      # what Excel produces is the ANSI codepage with CRLF, and the
+      # destination is a Linux path.
+      def export(name, path)
+        local_bridge!('export')
+        reject_dotdot!(path)
+        component = named_component!(name)
+        Dir.mktmpdir('wineole-vba') do |dir|
+          staged = ::File.join(dir, ::File.basename(path))
+          component.Export(Paths.to_wine(staged))
+          text = ::File.binread(staged).force_encoding(VBA.codepage).encode('UTF-8')
+          ::File.write(path, text.gsub("\r\n", "\n"))
+        end
+        self
+      end
+
+      # The workbook's VBA project, or an error that says what to do about
+      # it. The HRESULT and the message are both useless for telling this
+      # condition apart -- 0x800A03EC is what a rejected NumberFormat gives
+      # too, and the text is localized -- so the registry is what turns a
+      # refusal into advice.
+      def project
+        @ole.VBProject
+      rescue WineOLE::RemoteError
+        VBA.denied!
+      end
+
+      private
+
+      # The other direction, and it had been left bare: a file that reads
+      # cleanly can still hold a character the codepage cannot store, and
+      # #encode raised Encoding::UndefinedConversionError naming neither the
+      # file nor the way out. Same rule and same words as the string path --
+      # refuse rather than let Excel substitute in silence.
+      def to_codepage(text, path)
+        text.encode(VBA.codepage)
+      rescue ::Encoding::UndefinedConversionError => e
+        VBA.unrepresentable!(e.error_char, path.to_s)
+      end
+
+      # Both encodings can be wrong at once: the bytes are not valid UTF-8
+      # (which is what put us on the codepage branch) and not valid in the
+      # codepage either. Nothing can be inferred from that, so say so --
+      # a bare Encoding::InvalidByteSequenceError names neither the file
+      # nor why that encoding was the one tried.
+      def decode(raw, source, path, guessed:)
+        raw.dup.force_encoding(source).encode('UTF-8').sub(/\A\uFEFF/, '')
+      rescue ::Encoding::InvalidByteSequenceError, ::Encoding::UndefinedConversionError => e
+        why =
+          if guessed
+            "#{source} was tried because the file has no BOM and its bytes are not valid " \
+            "UTF-8, which rules UTF-8 out -- but they are not valid #{source} either, so " \
+            'there is nothing left to infer from. Pass `encoding:` if you know what this is'
+          else
+            "you passed encoding: #{source.inspect}, and the file's bytes are not valid in it"
+          end
+        raise ArgumentError, "cannot read #{path} as #{source} (#{e.message}). #{why}"
+      end
+
+      # These hand Excel a path to a file on this machine. When the bridge
+      # is somewhere else that path means that machine's filesystem, and
+      # there is no sensible thing to do with it.
+      #
+      # Keying this off @convert_paths (rather than a separate "is this
+      # loopback" flag) is deliberate, and it means a caller who passed
+      # convert_paths: false for a legitimate reason on a *loopback* bridge
+      # gets refused here too, with a message that says "needs the bridge to
+      # be on this machine" when it already is. That is the wrong reason but
+      # never the wrong direction: this can only over-refuse a bridge that
+      # would have worked, never under-refuse one that would not.
+      def local_bridge!(what)
+        return if @convert_paths
+
+        raise ArgumentError,
+          "#{what} needs the bridge to be on this machine: it stages a file " \
+          'and hands Excel the path, which means nothing on another host'
+      end
+
+      # File.basename of a path ending in ".." is literally "..". For import
+      # that path is read directly, so it already raises Errno::EISDIR of its
+      # own accord -- but a bare EISDIR does not say why. For export the same
+      # basename feeds File.join(dir, "..") when staging, which resolves to
+      # dir's *parent* rather than anywhere under our own tmpdir, and Export
+      # ends up trying to write a file over that directory -- also EISDIR,
+      # also confusing. Nothing escapes and nothing is corrupted either way;
+      # this just gives both a clear error instead of a bare Errno.
+      def reject_dotdot!(path)
+        return unless ::File.basename(path) == '..'
+
+        raise ArgumentError, "#{path.inspect} is not a usable file path (its basename is \"..\")"
+      end
+
+      def existing_component(name)
+        project.VBComponents.Item(name)
+      rescue WineOLE::RemoteError
+        nil
+      end
+
+      def target_module(into)
+        return own_module.CodeModule if into.nil?
+
+        named_component!(into).CodeModule
+      end
+
+      # This wrapper's own module, made on demand. Unlike a name the caller
+      # passed, this one cannot be a typo, so creating it silently is safe.
+      def own_module
+        found = existing_component(DEFAULT_MODULE)
+        return found unless found.nil?
+
+        component = project.VBComponents.Add(KINDS[:standard])
+        component.Name = DEFAULT_MODULE
+        component
+      end
+
+      def named_component!(name)
+        found = existing_component(name)
+        return found unless found.nil?
+
+        raise ArgumentError,
+          "this workbook has no VBA component named #{name.inspect}. " \
+          'Components are UserForms, ThisWorkbook, worksheet modules and ' \
+          'standard modules; add one with add_component, or omit `into:` ' \
+          'to use this wrapper\'s own module'
+      end
+    end
+
+    # The VBA surface of one worksheet, reached as `sheet.vba`.
+    #
+    # Blocks only. A worksheet's module cannot be created or deleted -- Excel
+    # makes it with the sheet and destroys it with the sheet -- so the
+    # component methods are absent here rather than present and always
+    # failing. Removing the last block empties the module; it does not
+    # remove it.
+    class SheetVBA
+      def initialize(ole)
+        @ole = ole
+      end
+
+      def write(code, name: 'main')
+        VBABlock.write(code_module, name, code)
+        self
+      end
+
+      def remove(name)
+        VBABlock.remove(code_module, name)
+        self
+      end
+
+      private
+
+      # A worksheet's handlers live in the worksheet's own code module --
+      # that is where Excel looks for `<ActiveX control>_Click`. The module
+      # is named by the sheet's CodeName, inside the parent workbook's
+      # project.
+      #
+      # THE ORDER OF THESE TWO LINES IS LOAD-BEARING, and it is not obvious.
+      # Worksheet.CodeName comes back as "" until something has touched that
+      # workbook's VBProject -- measured: "" before, "Sheet3" after, and
+      # "Sheet3" on every read from then on. Reading the name first and then
+      # the project (which looks like the same code, and is what extracting
+      # a local naturally produces) hands VBComponents.Item("") and gets
+      # 0x800A0009, "index out of range". So the project is fetched first,
+      # on purpose, and the name after it.
+      #
+      # The empty check is what keeps that from becoming a silent trap
+      # again: if this ever stops holding, it fails saying why instead of
+      # failing as a bare COM index error.
+      def code_module
+        vb_project = project
+        code_name = @ole.CodeName.to_s
+        if code_name.empty?
+          raise VBA::Error,
+            'this worksheet reports no CodeName even after its VBProject was opened, ' \
+            'so there is no way to find its code module'
+        end
+
+        vb_project.VBComponents.Item(code_name).CodeModule
+      end
+
+      # Only the VBProject fetch is the denial. Wrapping the lookup that
+      # follows it in the same rescue would report any other COM failure --
+      # a component that is not there, a module that will not open -- as
+      # "turn on AccessVBOM", which is advice for a condition the caller is
+      # not in.
+      def project
+        @ole.Parent.VBProject
+      rescue WineOLE::RemoteError
+        VBA.denied!
+      end
+    end
+  end
+end