Namespace: go.std.net.textproto

v1.0

Contents

• Summary
• Index
• Constants
• Variables
• Functions, Macros, and Special Forms
• Types

Summary

Provides a low-level interface to the net/textproto package.

Package textproto implements generic support for text-based request/response
protocols in the style of HTTP, NNTP, and SMTP.

The package provides:

Error, which represents a numeric error response from
a server.

Pipeline, to manage pipelined requests and responses
in a client.

Reader, to read numeric response code lines,
key: value headers, lines wrapped with leading spaces
on continuation lines, and whole text blocks ending
with a dot on a line by itself.

Writer, to write dot-encoded text blocks.

Conn, a convenient packaging of Reader, Writer, and Pipeline for use
with a single network connection.

Index

• *Conn
• *Error
• *MIMEHeader
• *Pipeline
• *ProtocolError
• *Reader
• *Writer
• CanonicalMIMEHeaderKey
• Conn
• Dial
• Error
• MIMEHeader
• NewConn
• NewReader
• NewWriter
• Pipeline
• ProtocolError
• Reader
• TrimBytes
• TrimString
• Writer
• arrayOfConn
• arrayOfError
• arrayOfMIMEHeader
• arrayOfPipeline
• arrayOfProtocolError
• arrayOfReader
• arrayOfWriter

Legend

Constant Variable Function Macro Special form Type GoVar Receiver/Method

Constants

Constants are variables with :const true in their metadata. Joker currently does not recognize them as special; as such, it allows redefining them or their values.

(None.)

Variables

(None.)

Functions, Macros, and Special Forms

• CanonicalMIMEHeaderKey

  Function v1.0

  (CanonicalMIMEHeaderKey s)
  

  CanonicalMIMEHeaderKey returns the canonical format of the
  MIME header key s. The canonicalization converts the first
  letter and any letter following a hyphen to upper case;
  the rest are converted to lowercase. For example, the
  canonical key for "accept-encoding" is "Accept-Encoding".
  MIME header keys are assumed to be ASCII only.
  If s contains a space or invalid header field bytes, it is
  returned without modifications.
  
  Go input arguments: (s string)
  
  Go returns: string
  
  Joker input arguments: [^String s]
  
  Joker returns: ^String

• Dial

  Function v1.0

  (Dial network addr)
  

  Dial connects to the given address on the given network using net.Dial
  and then returns a new Conn for the connection.
  
  Go input arguments: (network string, addr string)
  
  Go returns: (*Conn, error)
  
  Joker input arguments: [^String network, ^String addr]
  
  Joker returns: [^*Conn, ^Error]

• NewConn

  Function v1.0

  (NewConn conn)
  

  NewConn returns a new Conn using conn for I/O.
  
  Go input arguments: (conn io.ReadWriteCloser)
  
  Go returns: *Conn
  
  Joker input arguments: [^go.std.io/ReadWriteCloser conn]
  
  Joker returns: ^*Conn

• NewReader

  Function v1.0

  (NewReader r)
  

  NewReader returns a new Reader reading from r.
  
  To avoid denial of service attacks, the provided bufio.Reader
  should be reading from an io.LimitReader or similar Reader to bound
  the size of responses.
  
  Go input arguments: (r *bufio.Reader)
  
  Go returns: *Reader
  
  Joker input arguments: [^go.std.bufio/*Reader r]
  
  Joker returns: ^*Reader

• NewWriter

  Function v1.0

  (NewWriter w)
  

  NewWriter returns a new Writer writing to w.
  
  Go input arguments: (w *bufio.Writer)
  
  Go returns: *Writer
  
  Joker input arguments: [^go.std.bufio/*Writer w]
  
  Joker returns: ^*Writer

• TrimBytes

  Function v1.0

  (TrimBytes b)
  

  TrimBytes returns b without leading and trailing ASCII space.
  
  Go input arguments: (b []byte)
  
  Go returns: []byte
  
  Joker input arguments: [^arrayOfByte b]
  
  Joker returns: ^arrayOfByte

• TrimString

  Function v1.0

  (TrimString s)
  

  TrimString returns s without leading and trailing ASCII space.
  
  Go input arguments: (s string)
  
  Go returns: string
  
  Joker input arguments: [^String s]
  
  Joker returns: ^String

Types

• *Conn

  Concrete Type v1.0

  A Conn represents a textual network protocol connection.
  It consists of a Reader and Writer to manage I/O
  and a Pipeline to sequence concurrent requests on the connection.
  These embedded types carry methods with them;
  see the documentation of those types for details.
  

• Close

  Receiver for *Conn v1.0

  ([])
  

  Close closes the connection.
  

• Cmd

  Receiver for *Conn v1.0

  ([format args])
  

  Cmd is a convenience method that sends a command after
  waiting its turn in the pipeline. The command text is the
  result of formatting format with args and appending \r\n.
  Cmd returns the id of the command, for use with StartResponse and EndResponse.
  
  For example, a client might run a HELP command that returns a dot-body
  by using:
  
  id, err := c.Cmd("HELP")
  if err != nil {
  return nil, err
  }
  
  c.StartResponse(id)
  defer c.EndResponse(id)
  
  if _, _, err = c.ReadCodeLine(110); err != nil {
  return nil, err
  }
  text, err := c.ReadDotBytes()
  if err != nil {
  return nil, err
  }
  return c.ReadCodeLine(250)
  

• DotReader

  Receiver for *Conn v1.0

  ([])
  

  DotReader returns a new Reader that satisfies Reads using the
  decoded text of a dot-encoded block read from r.
  The returned Reader is only valid until the next call
  to a method on r.
  
  Dot encoding is a common framing used for data blocks
  in text protocols such as SMTP. The data consists of a sequence
  of lines, each of which ends in "\r\n". The sequence itself
  ends at a line containing just a dot: ".\r\n". Lines beginning
  with a dot are escaped with an additional dot to avoid
  looking like the end of the sequence.
  
  The decoded form returned by the Reader's Read method
  rewrites the "\r\n" line endings into the simpler "\n",
  removes leading dot escapes if present, and stops with error io.EOF
  after consuming (and discarding) the end-of-sequence line.
  

• DotWriter

  Receiver for *Conn v1.0

  ([])
  

  DotWriter returns a writer that can be used to write a dot-encoding to w.
  It takes care of inserting leading dots when necessary,
  translating line-ending \n into \r\n, and adding the final .\r\n line
  when the DotWriter is closed. The caller should close the
  DotWriter before the next call to a method on w.
  
  See the documentation for Reader's DotReader method for details about dot-encoding.
  

• EndRequest

  Receiver for *Conn v1.0

  ([id])
  

  EndRequest notifies p that the request with the given id has been sent
  (or, if this is a server, received).
  

• EndResponse

  Receiver for *Conn v1.0

  ([id])
  

  EndResponse notifies p that the response with the given id has been received
  (or, if this is a server, sent).
  

• Next

  Receiver for *Conn v1.0

  ([])
  

  Next returns the next id for a request/response pair.
  

• PrintfLine

  Receiver for *Conn v1.0

  ([format args])
  

  PrintfLine writes the formatted output followed by \r\n.
  

• ReadCodeLine

  Receiver for *Conn v1.0

  ([expectCode])
  

  ReadCodeLine reads a response code line of the form
  
  code message
  
  where code is a three-digit status code and the message
  extends to the rest of the line. An example of such a line is:
  
  220 plan9.bell-labs.com ESMTP
  
  If the prefix of the status does not match the digits in expectCode,
  ReadCodeLine returns with err set to &Error{code, message}.
  For example, if expectCode is 31, an error will be returned if
  the status is not in the range [310,319].
  
  If the response is multi-line, ReadCodeLine returns an error.
  
  An expectCode <= 0 disables the check of the status code.
  

• ReadContinuedLine

  Receiver for *Conn v1.0

  ([])
  

  ReadContinuedLine reads a possibly continued line from r,
  eliding the final trailing ASCII white space.
  Lines after the first are considered continuations if they
  begin with a space or tab character. In the returned data,
  continuation lines are separated from the previous line
  only by a single space: the newline and leading white space
  are removed.
  
  For example, consider this input:
  
  Line 1
  continued...
  Line 2
  
  The first call to ReadContinuedLine will return "Line 1 continued..."
  and the second will return "Line 2".
  
  Empty lines are never continued.
  

• ReadContinuedLineBytes

  Receiver for *Conn v1.0

  ([])
  

  ReadContinuedLineBytes is like ReadContinuedLine but
  returns a []byte instead of a string.
  

• ReadDotBytes

  Receiver for *Conn v1.0

  ([])
  

  ReadDotBytes reads a dot-encoding and returns the decoded data.
  
  See the documentation for the DotReader method for details about dot-encoding.
  

• ReadDotLines

  Receiver for *Conn v1.0

  ([])
  

  ReadDotLines reads a dot-encoding and returns a slice
  containing the decoded lines, with the final \r\n or \n elided from each.
  
  See the documentation for the DotReader method for details about dot-encoding.
  

• ReadLine

  Receiver for *Conn v1.0

  ([])
  

  ReadLine reads a single line from r,
  eliding the final \n or \r\n from the returned string.
  

• ReadLineBytes

  Receiver for *Conn v1.0

  ([])
  

  ReadLineBytes is like ReadLine but returns a []byte instead of a string.
  

• ReadMIMEHeader

  Receiver for *Conn v1.0

  ([])
  

  ReadMIMEHeader reads a MIME-style header from r.
  The header is a sequence of possibly continued Key: Value lines
  ending in a blank line.
  The returned map m maps CanonicalMIMEHeaderKey(key) to a
  sequence of values in the same order encountered in the input.
  
  For example, consider this input:
  
  My-Key: Value 1
  Long-Key: Even
  Longer Value
  My-Key: Value 2
  
  Given that input, ReadMIMEHeader returns the map:
  
  map[string][]string{
  "My-Key": {"Value 1", "Value 2"},
  "Long-Key": {"Even Longer Value"},
  }
  

• ReadResponse

  Receiver for *Conn v1.0

  ([expectCode])
  

  ReadResponse reads a multi-line response of the form:
  
  code-message line 1
  code-message line 2
  ...
  code message line n
  
  where code is a three-digit status code. The first line starts with the
  code and a hyphen. The response is terminated by a line that starts
  with the same code followed by a space. Each line in message is
  separated by a newline (\n).
  
  See page 36 of RFC 959 (https://www.ietf.org/rfc/rfc959.txt) for
  details of another form of response accepted:
  
  code-message line 1
  message line 2
  ...
  code message line n
  
  If the prefix of the status does not match the digits in expectCode,
  ReadResponse returns with err set to &Error{code, message}.
  For example, if expectCode is 31, an error will be returned if
  the status is not in the range [310,319].
  
  An expectCode <= 0 disables the check of the status code.
  

• StartRequest

  Receiver for *Conn v1.0

  ([id])
  

  StartRequest blocks until it is time to send (or, if this is a server, receive)
  the request with the given id.
  

• StartResponse

  Receiver for *Conn v1.0

  ([id])
  

  StartResponse blocks until it is time to receive (or, if this is a server, send)
  the request with the given id.
  

• *Error

  Concrete Type v1.0

  An Error represents a numeric error response from a server.
  

• Error

  Receiver for *Error v1.0

  ([])
  

• *MIMEHeader

  Concrete Type v1.0

  A MIMEHeader represents a MIME-style header mapping
  keys to sets of values.
  

• *Pipeline

  Concrete Type v1.0

  A Pipeline manages a pipelined in-order request/response sequence.
  
  To use a Pipeline p to manage multiple clients on a connection,
  each client should run:
  
  id := p.Next() // take a number
  
  p.StartRequest(id) // wait for turn to send request
  «send request»
  p.EndRequest(id) // notify Pipeline that request is sent
  
  p.StartResponse(id) // wait for turn to read response
  «read response»
  p.EndResponse(id) // notify Pipeline that response is read
  
  A pipelined server can use the same calls to ensure that
  responses computed in parallel are written in the correct order.
  

• EndRequest

  Receiver for *Pipeline v1.0

  ([id])
  

  EndRequest notifies p that the request with the given id has been sent
  (or, if this is a server, received).
  

• EndResponse

  Receiver for *Pipeline v1.0

  ([id])
  

  EndResponse notifies p that the response with the given id has been received
  (or, if this is a server, sent).
  

• Next

  Receiver for *Pipeline v1.0

  ([])
  

  Next returns the next id for a request/response pair.
  

• StartRequest

  Receiver for *Pipeline v1.0

  ([id])
  

  StartRequest blocks until it is time to send (or, if this is a server, receive)
  the request with the given id.
  

• StartResponse

  Receiver for *Pipeline v1.0

  ([id])
  

  StartResponse blocks until it is time to receive (or, if this is a server, send)
  the request with the given id.
  

• *ProtocolError

  Concrete Type v1.0

  A ProtocolError describes a protocol violation such
  as an invalid response or a hung-up connection.
  

• *Reader

  Concrete Type v1.0

  A Reader implements convenience methods for reading requests
  or responses from a text protocol network connection.
  

• DotReader

  Receiver for *Reader v1.0

  ([])
  

  DotReader returns a new Reader that satisfies Reads using the
  decoded text of a dot-encoded block read from r.
  The returned Reader is only valid until the next call
  to a method on r.
  
  Dot encoding is a common framing used for data blocks
  in text protocols such as SMTP. The data consists of a sequence
  of lines, each of which ends in "\r\n". The sequence itself
  ends at a line containing just a dot: ".\r\n". Lines beginning
  with a dot are escaped with an additional dot to avoid
  looking like the end of the sequence.
  
  The decoded form returned by the Reader's Read method
  rewrites the "\r\n" line endings into the simpler "\n",
  removes leading dot escapes if present, and stops with error io.EOF
  after consuming (and discarding) the end-of-sequence line.
  

• ReadCodeLine

  Receiver for *Reader v1.0

  ([expectCode])
  

  ReadCodeLine reads a response code line of the form
  
  code message
  
  where code is a three-digit status code and the message
  extends to the rest of the line. An example of such a line is:
  
  220 plan9.bell-labs.com ESMTP
  
  If the prefix of the status does not match the digits in expectCode,
  ReadCodeLine returns with err set to &Error{code, message}.
  For example, if expectCode is 31, an error will be returned if
  the status is not in the range [310,319].
  
  If the response is multi-line, ReadCodeLine returns an error.
  
  An expectCode <= 0 disables the check of the status code.
  

• ReadContinuedLine

  Receiver for *Reader v1.0

  ([])
  

  ReadContinuedLine reads a possibly continued line from r,
  eliding the final trailing ASCII white space.
  Lines after the first are considered continuations if they
  begin with a space or tab character. In the returned data,
  continuation lines are separated from the previous line
  only by a single space: the newline and leading white space
  are removed.
  
  For example, consider this input:
  
  Line 1
  continued...
  Line 2
  
  The first call to ReadContinuedLine will return "Line 1 continued..."
  and the second will return "Line 2".
  
  Empty lines are never continued.
  

• ReadContinuedLineBytes

  Receiver for *Reader v1.0

  ([])
  

  ReadContinuedLineBytes is like ReadContinuedLine but
  returns a []byte instead of a string.
  

• ReadDotBytes

  Receiver for *Reader v1.0

  ([])
  

  ReadDotBytes reads a dot-encoding and returns the decoded data.
  
  See the documentation for the DotReader method for details about dot-encoding.
  

• ReadDotLines

  Receiver for *Reader v1.0

  ([])
  

  ReadDotLines reads a dot-encoding and returns a slice
  containing the decoded lines, with the final \r\n or \n elided from each.
  
  See the documentation for the DotReader method for details about dot-encoding.
  

• ReadLine

  Receiver for *Reader v1.0

  ([])
  

  ReadLine reads a single line from r,
  eliding the final \n or \r\n from the returned string.
  

• ReadLineBytes

  Receiver for *Reader v1.0

  ([])
  

  ReadLineBytes is like ReadLine but returns a []byte instead of a string.
  

• ReadMIMEHeader

  Receiver for *Reader v1.0

  ([])
  

  ReadMIMEHeader reads a MIME-style header from r.
  The header is a sequence of possibly continued Key: Value lines
  ending in a blank line.
  The returned map m maps CanonicalMIMEHeaderKey(key) to a
  sequence of values in the same order encountered in the input.
  
  For example, consider this input:
  
  My-Key: Value 1
  Long-Key: Even
  Longer Value
  My-Key: Value 2
  
  Given that input, ReadMIMEHeader returns the map:
  
  map[string][]string{
  "My-Key": {"Value 1", "Value 2"},
  "Long-Key": {"Even Longer Value"},
  }
  

• ReadResponse

  Receiver for *Reader v1.0

  ([expectCode])
  

  ReadResponse reads a multi-line response of the form:
  
  code-message line 1
  code-message line 2
  ...
  code message line n
  
  where code is a three-digit status code. The first line starts with the
  code and a hyphen. The response is terminated by a line that starts
  with the same code followed by a space. Each line in message is
  separated by a newline (\n).
  
  See page 36 of RFC 959 (https://www.ietf.org/rfc/rfc959.txt) for
  details of another form of response accepted:
  
  code-message line 1
  message line 2
  ...
  code message line n
  
  If the prefix of the status does not match the digits in expectCode,
  ReadResponse returns with err set to &Error{code, message}.
  For example, if expectCode is 31, an error will be returned if
  the status is not in the range [310,319].
  
  An expectCode <= 0 disables the check of the status code.
  

• *Writer

  Concrete Type v1.0

  A Writer implements convenience methods for writing
  requests or responses to a text protocol network connection.
  

• DotWriter

  Receiver for *Writer v1.0

  ([])
  

  DotWriter returns a writer that can be used to write a dot-encoding to w.
  It takes care of inserting leading dots when necessary,
  translating line-ending \n into \r\n, and adding the final .\r\n line
  when the DotWriter is closed. The caller should close the
  DotWriter before the next call to a method on w.
  
  See the documentation for Reader's DotReader method for details about dot-encoding.
  

• PrintfLine

  Receiver for *Writer v1.0

  ([format args])
  

  PrintfLine writes the formatted output followed by \r\n.
  

• Conn

  Concrete Type v1.0

  A Conn represents a textual network protocol connection.
  It consists of a Reader and Writer to manage I/O
  and a Pipeline to sequence concurrent requests on the connection.
  These embedded types carry methods with them;
  see the documentation of those types for details.
  

• Error

  Concrete Type v1.0

  An Error represents a numeric error response from a server.
  

• MIMEHeader

  Concrete Type v1.0

  A MIMEHeader represents a MIME-style header mapping
  keys to sets of values.
  

• Add

  Receiver for MIMEHeader v1.0

  ([key value])
  

  Add adds the key, value pair to the header.
  It appends to any existing values associated with key.
  

• Del

  Receiver for MIMEHeader v1.0

  ([key])
  

  Del deletes the values associated with key.
  

• Get

  Receiver for MIMEHeader v1.0

  ([key])
  

  Get gets the first value associated with the given key.
  It is case insensitive; CanonicalMIMEHeaderKey is used
  to canonicalize the provided key.
  If there are no values associated with the key, Get returns "".
  To use non-canonical keys, access the map directly.
  

• Set

  Receiver for MIMEHeader v1.0

  ([key value])
  

  Set sets the header entries associated with key to
  the single element value. It replaces any existing
  values associated with key.
  

• Values

  Receiver for MIMEHeader v1.0

  ([key])
  

  Values returns all values associated with the given key.
  It is case insensitive; CanonicalMIMEHeaderKey is
  used to canonicalize the provided key. To use non-canonical
  keys, access the map directly.
  The returned slice is not a copy.
  

• Pipeline

  Concrete Type v1.0

  A Pipeline manages a pipelined in-order request/response sequence.
  
  To use a Pipeline p to manage multiple clients on a connection,
  each client should run:
  
  id := p.Next() // take a number
  
  p.StartRequest(id) // wait for turn to send request
  «send request»
  p.EndRequest(id) // notify Pipeline that request is sent
  
  p.StartResponse(id) // wait for turn to read response
  «read response»
  p.EndResponse(id) // notify Pipeline that response is read
  
  A pipelined server can use the same calls to ensure that
  responses computed in parallel are written in the correct order.
  

• ProtocolError

  Concrete Type v1.0

  A ProtocolError describes a protocol violation such
  as an invalid response or a hung-up connection.
  

• Error

  Receiver for ProtocolError v1.0

  ([])
  

• Reader

  Concrete Type v1.0

  A Reader implements convenience methods for reading requests
  or responses from a text protocol network connection.
  

• Writer

  Concrete Type v1.0

  A Writer implements convenience methods for writing
  requests or responses to a text protocol network connection.
  

• arrayOfConn

  Concrete Type v1.0

  A Conn represents a textual network protocol connection.
  It consists of a Reader and Writer to manage I/O
  and a Pipeline to sequence concurrent requests on the connection.
  These embedded types carry methods with them;
  see the documentation of those types for details.
  

• arrayOfError

  Concrete Type v1.0

  An Error represents a numeric error response from a server.
  

• arrayOfMIMEHeader

  Concrete Type v1.0

  A MIMEHeader represents a MIME-style header mapping
  keys to sets of values.
  

• arrayOfPipeline

  Concrete Type v1.0

  A Pipeline manages a pipelined in-order request/response sequence.
  
  To use a Pipeline p to manage multiple clients on a connection,
  each client should run:
  
  id := p.Next() // take a number
  
  p.StartRequest(id) // wait for turn to send request
  «send request»
  p.EndRequest(id) // notify Pipeline that request is sent
  
  p.StartResponse(id) // wait for turn to read response
  «read response»
  p.EndResponse(id) // notify Pipeline that response is read
  
  A pipelined server can use the same calls to ensure that
  responses computed in parallel are written in the correct order.
  

• arrayOfProtocolError

  Concrete Type v1.0

  A ProtocolError describes a protocol violation such
  as an invalid response or a hung-up connection.
  

• arrayOfReader

  Concrete Type v1.0

  A Reader implements convenience methods for reading requests
  or responses from a text protocol network connection.
  

• arrayOfWriter

  Concrete Type v1.0

  A Writer implements convenience methods for writing
  requests or responses to a text protocol network connection.