Documentation
¶
Overview ¶
Package sourcemapx contains utilities for passing source map information around, intended to work with a [neelance sourcemap].
Mapping Go source coude ¶
GopherJS code generator outputs hints about correspondence between the generated code and original sources inline. Such hints are marked by the special `\b` (0x08) magic byte, followed by a variable-length sequence of bytes, which can be extracted from the byte slice using ReadHint() function.
'\b' was chosen as a magic symbol because it would never occur unescaped in the generated code, other than when explicitly inserted by the source mapping hint. See Hint type documentation for the details of the encoded format.
The hinting mechanism is designed to be extensible, the Hint type able to wrap different types containing different information:
- go/token.Pos indicates position in the original source the current location in the generated code corresponds to.
- Identifier maps a JS identifier to the original Go identifier it represents.
More types may be added in future if necessary.
Filter type is used to extract the hints from the written code stream and pass them into source map generator. It also ensures that the encoded inline hints don't make it into the final output, since they are not valid JS.
Mapping JS source code ¶
The filter also provides a WriteJS methods that can be used to write pure JS code (without hints) through the filter. While it is passing through the filter, it will produce a source map for the JS code and pass that source map information to a [neelance sourcemap]. This uses [esbuild]
[neelance sourcemap]:github.com/neelance/sourcemap [esbuild]: https://esbuild.github.io/
Index ¶
- Constants
- func FindHint(b []byte) int
- type Filter
- func (f *Filter) EnableMapping(jsFileName, goroot, gopath string, localMap bool)
- func (f *Filter) IsMapping() bool
- func (f *Filter) Write(p []byte) (n int, err error)
- func (f *Filter) WriteJS(jsSource, jsFilePath string, minify bool) (n int, err error)
- func (f *Filter) WriteMappingTo(w io.Writer) error
- type Hint
- type Identifier
Constants ¶
const HintMagic byte = '\b'
A magic byte in the generated code output that indicates a beginning of a source map hint. The character has been chosen because it should never show up in valid generated code unescaped, other than for source map hint purposes.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Filter ¶
type Filter struct {
Writer io.Writer
FileSet *token.FileSet
// contains filtered or unexported fields
}
Filter implements io.Writer which extracts source map hints from the written stream and passed them to the MappingCallback if it's not nil. Encoded hints are always filtered out of the output stream.
func (*Filter) EnableMapping ¶
type Hint ¶
type Hint struct {
Payload []byte
}
Hint is a container for a sourcemap hint that can be embedded into the generated code stream. Payload size and semantics depend on the nature of the hint.
Within the stream, the hint is encoded in the following binary format:
- magic: 0x08 - ASCII backspace, magic symbol indicating the beginning of the hint;
- size: 16 bit, big endian unsigned int - the size of the payload.
- payload: [size]byte - the payload of the hint.
func ReadHint ¶
ReadHint reads the Hint from the beginning of the byte slice and returns the hint and the number of bytes in the slice it occupies. The caller is expected to find the location of the hint using FindHint prior to calling this function.
Returned hint payload does not share backing array with b.
Function panics if:
- b[0] != '\b'
- len(b) < size + 3
func (*Hint) Pack ¶
Pack the given value into hint's payload.
Supported types: go/token.Pos.
The first byte of the payload will indicate the encoded type, and the rest is an opaque, type-dependent binary representation of the type.
type Identifier ¶
type Identifier struct {
Name string // Identifier to use in the generated code.
OriginalName string // Original identifier name.
OriginalPos token.Pos // Original identifier position.
}
Identifier represents a generated code identifier with a the associated original identifier information, which can be used to produce a source map.
This allows us to map a JS function or variable name back to the original Go symbol name.
func (Identifier) EncodeHint ¶
func (i Identifier) EncodeHint() string
EncodeHint returns a string with an encoded source map hint. The hint can be inserted into the generated code to be later extracted by the SourceMapFilter to produce a source map.
func (Identifier) String ¶
func (i Identifier) String() string
String returns generated code identifier name.
Source Files