-
Notifications
You must be signed in to change notification settings - Fork 1
/
as.character.srcref.html
207 lines (179 loc) · 7.4 KB
/
as.character.srcref.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html><head><title>R: References to source files</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="R.css">
</head><body>
<table width="100%" summary="page for srcfile"><tr><td>srcfile</td><td align="right">R Documentation</td></tr></table>
<h2>References to source files</h2>
<h3>Description</h3>
<p>These functions are for working with source files.
</p>
<h3>Usage</h3>
<pre>
srcfile(filename, encoding = getOption("encoding"), Enc = "unknown")
srcfilecopy(filename, lines, timestamp = Sys.time(), isFile = FALSE)
srcfilealias(filename, srcfile)
getSrcLines(srcfile, first, last)
srcref(srcfile, lloc)
## S3 method for class 'srcfile'
print(x, ...)
## S3 method for class 'srcfile'
summary(object, ...)
## S3 method for class 'srcfile'
open(con, line, ...)
## S3 method for class 'srcfile'
close(con, ...)
## S3 method for class 'srcref'
print(x, useSource = TRUE, ...)
## S3 method for class 'srcref'
summary(object, useSource = FALSE, ...)
## S3 method for class 'srcref'
as.character(x, useSource = TRUE, ...)
.isOpen(srcfile)
</pre>
<h3>Arguments</h3>
<table summary="R argblock">
<tr valign="top"><td><code>filename</code></td>
<td>
<p> The name of a file. </p>
</td></tr>
<tr valign="top"><td><code>encoding</code></td>
<td>
<p> The character encoding to assume for the file. </p>
</td></tr>
<tr valign="top"><td><code>Enc</code></td>
<td>
<p> The encoding with which to make strings: see the
<code>encoding</code> argument of <code>parse</code>.</p>
</td></tr>
<tr valign="top"><td><code>lines</code></td>
<td>
<p> A character vector of source lines. Other <font face="Courier New,Courier" color="#666666"><b>R</b></font> objects
will be coerced to character. </p>
</td></tr>
<tr valign="top"><td><code>timestamp</code></td>
<td>
<p> The timestamp to use on a copy of a file. </p>
</td></tr>
<tr valign="top"><td><code>isFile</code></td>
<td>
<p> Is this <code>srcfilecopy</code> known to come from a file system file? </p>
</td></tr>
<tr valign="top"><td><code>srcfile</code></td>
<td>
<p> A <code>srcfile</code> object. </p>
</td></tr>
<tr valign="top"><td><code>first, last, line</code></td>
<td>
<p> Line numbers. </p>
</td></tr>
<tr valign="top"><td><code>lloc</code></td>
<td>
<p> A vector of four, six or eight values giving a source location; see
‘Details’.</p>
</td></tr>
<tr valign="top"><td><code>x, object, con</code></td>
<td>
<p> An object of the appropriate class. </p>
</td></tr>
<tr valign="top"><td><code>useSource</code></td>
<td>
<p> Whether to read the <code>srcfile</code> to obtain the
text of a <code>srcref</code>. </p>
</td></tr>
<tr valign="top"><td><code>...</code></td>
<td>
<p> Additional arguments to the methods; these will be ignored. </p>
</td></tr>
</table>
<h3>Details</h3>
<p>These functions and classes handle source code references.
</p>
<p>The <code>srcfile</code> function produces an object of class
<code>srcfile</code>, which contains the name and directory of a source code
file, along with its timestamp, for use in source level debugging (not
yet implemented) and source echoing. The encoding of the file is
saved; see <code>file</code> for a discussion of encodings, and
<code>iconvlist</code> for a list of allowable encodings on your platform.
</p>
<p>The <code>srcfilecopy</code> function produces an object of the descendant
class <code>srcfilecopy</code>, which saves the source lines in a character
vector. It copies the value of the <code>isFile</code> argument, to help
debuggers identify whether this text comes from a real file in the
file system.
</p>
<p>The <code>srcfilealias</code> function produces an object of the descendant
class <code>srcfilealias</code>, which gives an alternate name to another
srcfile. This is produced by the parser when a <code>#line</code> directive
is used.
</p>
<p>The <code>getSrcLines</code> function reads the specified lines from
<code>srcfile</code>.
</p>
<p>The <code>srcref</code> function produces an object of class
<code>srcref</code>, which describes a range of characters in a <code>
srcfile</code>. The <code>lloc</code> value gives the following values: <code>c
(first_line, first_byte, last_line, last_byte, first_column,
last_column, first_parsed, last_parsed)</code>. Bytes (elements 2, 4) and
columns (elements 5, 6) may be different due to multibyte
characters. If only four values are given, the columns and bytes
are assumed to match. Lines (elements 1, 3) and parsed lines (
elements 7, 8) may differ if a <code>#line</code> directive is used in
code: the former will respect the directive, the latter will just
count lines. If only 4 or 6 elements are given, the parsed lines
will be assumed to match the lines.
</p>
<p>Methods are defined for <code>print</code>, <code>summary</code>, <code>open</code>,
and <code>close</code> for classes <code>srcfile</code> and <code>srcfilecopy</code>.
The <code>open</code> method opens its internal <code>file</code> connection at
a particular line; if it was already open, it will be repositioned
to that line.
</p>
<p>Methods are defined for <code>print</code>, <code>summary</code> and
<code>as.character</code> for class <code>srcref</code>. The <code>as.character</code>
method will read the associated source file to obtain the text
corresponding to the reference. The exact behaviour depends on the
class of the source file. If the source file inherits from
class <code>"srcfilecopy"</code>, the lines are taken from the saved copy
using the "parsed" line counts. If not, an attempt
is made to read the file, and the original line numbers of the
<code>srcref</code> record (i.e. elements 1 and 3) are used. If an error
occurs (e.g. the file no longer exists), text like
<code><srcref: "file" chars 1:1 to 2:10></code> will be returned instead,
indicating the <code>line:column</code> ranges of the first and last
character. The <code>summary</code> method defaults to this type of
display.
</p>
<p>Lists of <code>srcref</code> objects may be attached to expressions as the
<code>"srcref"</code> attribute. (The list of <code>srcref</code> objects should be the same
length as the expression.) By default, expressions are printed by
<code>print.default</code> using the associated <code>srcref</code>. To
see deparsed code instead, call <code>print</code> with argument
<code>useSource = FALSE</code>. If a <code>srcref</code> object
is printed with <code>useSource = FALSE</code>, the <code><srcref: ...></code>
record will be printed.
</p>
<p><code>.isOpen</code> is intended for internal use: it checks whether the
connection associated with a <code>srcfile</code> object is open.
</p>
<h3>Value</h3>
<p><code>srcfile</code> returns a <code>srcfile</code> object.
</p>
<p><code>srcfilecopy</code> returns a <code>srcfilecopy</code> object.
</p>
<p><code>getSrcLines</code> returns a character vector of source code lines.
</p>
<p><code>srcref</code> returns a <code>srcref</code> object.
</p>
<h3>Author(s)</h3>
<p>Duncan Murdoch</p>
<h3>Examples</h3>
<pre> # has timestamp
src <- srcfile(system.file("DESCRIPTION", package = "base"))
summary(src)
getSrcLines(src, 1, 4)
ref <- srcref(src, c(1, 1, 2, 1000))
ref
print(ref, useSource = FALSE)
</pre>
</body></html>