Module: Anydoc

Defined in:
lib/anydoc.rb,
lib/anydoc/errors.rb,
lib/anydoc/version.rb,
lib/anydoc/document.rb,
sig/anydoc.rbs

Overview

Convert documents (Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, and PDF) to GitHub-Flavored Markdown.

Anydoc.to_markdown("report.docx")

Every format parses into one shared document model and renders through a single Markdown serializer, so headings, tables, lists, and footnotes come out the same no matter which format goes in.

See Also:

Defined Under Namespace

Modules: Native Classes: Asset, Block, Cell, CellSlot, ConvertError, Document, EncryptedError, Error, ImageSource, Inline, LinkTarget, List, ListItem, MalformedError, MissingPartError, Note, ResourceLimitError, Style, Table, UnsupportedError

Constant Summary collapse

VERSION =

The gem version, which is the version of the anydoc crate it wraps.

Returns:

  • (String) 
"0.1.8"
FORMATS =

Every format anydoc reads, named after the extension that identifies it.

Returns:

  • (Array[Symbol]) 

      
    

  







  
    

      Class Method Summary
      collapse
    


    
    
  



  

    
Class Method Details


    
      

  

  
    .format_from_bytes(data)  ⇒ Symbol? 
  

  

  


  

    
Detect the format from the content itself: the signature and identity
each container specification designates (PDF header, RTF open group, OLE
stream names, ZIP package mimetype/content types).


  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (String)
      
      
      
        —
        
    the document's bytes.
    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Symbol, nil)
      
      
      
        —
        
    nil for plain-text formats, which carry no
signature, and for anything unrecognized.
    
      
    
    • 
  





  

    
      


93
94
95

    		
    
      
# File 'lib/anydoc.rb', line 93

def format_from_bytes(data)
  Native.format_from_bytes(data)
end

    		
  





    
      

  

  
    .format_from_extension(extension)  ⇒ Symbol? 
  

  

  


  

    
The format an extension names, with or without a leading dot, matched
case-insensitively.


  





  
Parameters:


    
  
    
  • 
      
        extension
      
      
        (String, Symbol)
      
      
      
        —
        
    e.g. ".pptm".
    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Symbol, nil)
      
      
      
        —
        
    nil for anything unrecognized.
    
      
    
    • 
  





  

    
      


102
103
104

    		
    
      
# File 'lib/anydoc.rb', line 102

def format_from_extension(extension)
  Native.format_from_extension(extension.to_s.delete_prefix("."))
end

    		
  





    
      

  

  
    .format_from_path(path)  ⇒ Symbol? 
  

  

  


  

    
The format a path's extension names.


  





  
Parameters:


    
  
    
  • 
      
        path
      
      
        (String, Pathname)
      
      
      
        —
        
    the path to read the extension off.
    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Symbol, nil)
      
      
      
        —
        
    nil when the path has no extension or names
nothing recognized.
    
      
    
    • 
  





  

    
      


111
112
113
114

    		
    
      
# File 'lib/anydoc.rb', line 111

def format_from_path(path)
  extension = File.extname(File.path(path))
  extension.empty? ? nil : format_from_extension(extension)
end

    		
  





    
      

  

  
    .to_document(data, format: nil)  ⇒ Document 
  

  

  


  

    
Parse an in-memory document into the document model, which also carries
the embedded assets.


Unsupported for :pdf: PDF conversion produces Markdown directly and
has no document-model form; use to_markdown_bytes.


  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (String)
      
      
      
        —
        
    the document's bytes.
    
      
    
    • 
  
    
  • 
      
        format
      
      
        (Symbol, String, nil)
      
      
        (defaults to: nil)
      
      
        —
        
    which format to parse it as. Left
out, the format is detected from the content.
    
      
    
    • 
  
    
  • 
      
        format:
      
      
        (format, nil)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Returns:



Raises:


    
  
    
  • 
      
      
        (ConvertError)
      
      
      
        —
        
    if the document could not be parsed.
    
      
    
    • 
  
    
  • 
      
      
        (ArgumentError)
      
      
      
        —
        
    if format names no supported format.
    
      
    
    • 
  





  

    
      


82
83
84

    		
    
      
# File 'lib/anydoc.rb', line 82

def to_document(data, format: nil)
  Native.to_document(data, format_symbol(format))
end

    		
  





    
      

  

  
    .to_markdown(path)  ⇒ String 
  

  

  


  

    
Convert a document file to Markdown. The format is detected from the
file content; the extension is the fallback for signature-less formats
(CSV) and unrecognizable containers.


  





  
Parameters:


    
  
    
  • 
      
        path
      
      
        (String, Pathname)
      
      
      
        —
        
    the file to convert.
    
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    GitHub-Flavored Markdown.
    
      
    
    • 
  



Raises:


    
  
    
  • 
      
      
        (ConvertError)
      
      
      
        —
        
    if no meaningful Markdown could come out of it.
    
      
    
    • 
  
    
  • 
      
      
        (SystemCallError)
      
      
      
        —
        
    if the file could not be read.
    
      
    
    • 
  





  

    
      


45
46
47
48
49
50
51
52
53
54
55

    		
    
      
# File 'lib/anydoc.rb', line 45

def to_markdown(path)
  path = File.path(path)
  data = File.binread(path)
  format = format_from_bytes(data) || format_from_path(path)
  unless format
    raise UnsupportedError,
          "unsupported input: unrecognized file content and extension: #{path}"
  end

  to_markdown_bytes(data, format: format)
end

    		
  





    
      

  

  
    .to_markdown_bytes(data, format: nil)  ⇒ String 
  

  

  


  

    
Convert an in-memory document to Markdown.


  





  
Parameters:


    
  
    
  • 
      
        data
      
      
        (String)
      
      
      
        —
        
    the document's bytes.
    
      
    
    • 
  
    
  • 
      
        format
      
      
        (Symbol, String, nil)
      
      
        (defaults to: nil)
      
      
        —
        
    which format to parse it as. Left
out, the format is detected from the content, which signature-less
formats (CSV) have to name explicitly.
    
      
    
    • 
  
    
  • 
      
        format:
      
      
        (format, nil)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (String)
      
      
      
        —
        
    GitHub-Flavored Markdown.
    
      
    
    • 
  



Raises:


    
  
    
  • 
      
      
        (ConvertError)
      
      
      
        —
        
    if no meaningful Markdown could come out of it.
    
      
    
    • 
  
    
  • 
      
      
        (ArgumentError)
      
      
      
        —
        
    if format names no supported format.
    
      
    
    • 
  





  

    
      


66
67
68

    		
    
      
# File 'lib/anydoc.rb', line 66

def to_markdown_bytes(data, format: nil)
  Native.to_markdown_bytes(data, format_symbol(format))
end