Class: Texd::AttachmentList

Inherits:
Object
  • Object
show all
Defined in:
lib/texd/attachment.rb

Overview

AttachmentList will contain file references used in tex documents. This class is commonly interacted with in the ‘attach_file` view helper:

Examples:

Name mangling is active by default:

\input{<%= attach_file "/path/to/reference.tex" %>}
% might render as:
\input{att-1234.tex}

Name mangling can be deactivated:

\input{<%= attach_file "/path/to/reference.tex", rename: false %>}
% will render as:
\input{reference.tex}

Some situations require to drop the file extension:

\usepackage{<%= attach_file "helper.sty", rename: false, extension: false %>}
% will render as:
\usepackage{helper}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(lookup_context) ⇒ AttachmentList

Returns a new instance of AttachmentList.

Parameters:



27
28
29
30
 
# File 'lib/texd/attachment.rb', line 27

def initialize(lookup_context)
  @items          = {}
  @lookup_context = lookup_context
end

Instance Attribute Details

#items ⇒ Object (readonly)

Returns the value of attribute items.



23
24
25
 
# File 'lib/texd/attachment.rb', line 23

def items
  @items
end

#lookup_context ⇒ Object (readonly)

Returns the value of attribute lookup_context.



24
25
26
 
# File 'lib/texd/attachment.rb', line 24

def lookup_context
  @lookup_context
end

Instance Method Details

#attach(path, rename = true) ⇒ Attachment::File

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Adds a file with the given ‘path` to the list. The file path must either be an absolute filename or be relative to app/tex/ of the host application. See `Texd::LookupContext` for details.

The output file name will be mangled, unless ‘rename` specifies a name to use. Setting `rename` to false also disables renaming (the output will then use the file’s basename unaltered).

Note: Adding the same ‘path` twice with different arguments will have no effect: The returned value on the second attempt will be the same as on the first one.

Parameters:

  • path (String, Pathname) —

    partial path

  • rename (Boolean, String) (defaults to: true) —

    affects the output file name. If ‘true`, a random file name is generated for the TeX template, `false` will use the basename of path. When a string is given, that string is used instead. Be careful to avoid name collisions.

Returns:



52
53
54
 
# File 'lib/texd/attachment.rb', line 52

def attach(path, rename = true) # rubocop:disable Style/OptionalBooleanParameter
  add(Attachment::File, path, rename)
end

#inline(contents, path) ⇒ <Type>

Includes a file with the given ‘content` to the list. This is useful if you generate the content on-the-fly (like creating CSV data from database records), and don’t want to save that content to disk first.

In short, these examples should be mostly equivalent:

# use a temporary file to write contents to, and attach that file:
tmp = Tempfile.new ["foo", ".csv"]
tmp.write @record.to_csv
tmp.flush
tmp.close
text_attach tmp.name

# skip writing to disk and inline the file:
texd_inline @record.to_csv, "foo.csv"

Parameters:

  • contents (<Type>) —

    <description>

  • path (<Type>) —

    <description>

Returns:

  • (<Type>) —

    <description>



76
77
78
79
80
81
 
# File 'lib/texd/attachment.rb', line 76

def inline(contents, path)
  att = Attachment::Dynamic.new(path, contents)

  items[att.name] ||= att
  items[att.name]
end

#main_input(contents) ⇒ String

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Adds main input file for the render request. The returned name for this file is either “input.tex”, or (if that name already exist) some alternative. You should add the return value as input parameter to the client’s render call.

Parameters:

  • contents (String) —

    of main input.

Returns:

  • (String) —

    a generated name, usually “input.tex”



119
120
121
122
123
124
125
126
127
 
# File 'lib/texd/attachment.rb', line 119

def main_input(contents)
  name = "input.tex"
  i    = 0
  name = format("doc%05d.tex", i += 1) while items.key?(name)
  att  = Attachment::Dynamic.new(name, contents)

  items[name] = att
  items[name]
end

#reference(path, rename = false) ⇒ Attachment::Reference

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Adds a file reference with the given path to the list. Similar to #attach, the file path must either be an absolute filename or be relative to app/tex/ of the host application.

File name mangling applies as well, with the same rules as in #attach.

File references allow to reduce the amount of data sent to the texd server instance, by initially only sending the file’s checksums. If the server can identify that checksum from an internal store, it’ll use the stored file. Otherwise we receive a list of unknown references, and can retry the render request with the missing content attached in full.

References will be stored on the server (for some amount of time), so you should only attach static files, which change seldomly. Do not add dynamic content.

Parameters:

  • path (String, Pathname) —

    partial path

  • rename (Boolean, String) (defaults to: false) —

    affects the output file name. If ‘true`, a random file name is generated for the TeX template, `false` will use the basename of path. When a string is given, that string is used instead. Be careful to avoid name collisions.

Returns:



107
108
109
 
# File 'lib/texd/attachment.rb', line 107

def reference(path, rename = false) # rubocop:disable Style/OptionalBooleanParameter
  add(Attachment::Reference, path, rename)
end

#to_upload_ios(unknown_reference_ids = nil) ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Transforms this list to UploadIO objects suitable for Texd::Client#render.

Parameters:

  • unknown_reference_ids (Set|nil) (defaults to: nil) —

    file references to be included fully.



133
134
135
136
137
138
139
140
141
 
# File 'lib/texd/attachment.rb', line 133

def to_upload_ios(unknown_reference_ids = nil)
  items.values.each_with_object({}) { |att, ios|
    ios[att.name] = if unknown_reference_ids && att.is_a?(Attachment::Reference)
      att.to_upload_io(full: unknown_reference_ids.include?(att.checksum))
    else
      att.to_upload_io
    end
  }
end