BASIS 2 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
ASCII grammar

Table, encoder, wire validator and decoders. More...

Classes

struct  alicat_basis2::ascii::CommandSpec
 One row of the command table (rows C01 to C46). More...
 
struct  alicat_basis2::ascii::Args
 The arguments of a request before encoding. More...
 
struct  alicat_basis2::ascii::Token
 One token: where it starts and how long it is. More...
 
struct  alicat_basis2::ascii::Tokens
 The tokens of a line. More...
 
struct  alicat_basis2::ascii::FrameRules
 The rules a decoded frame is checked against. More...
 
struct  alicat_basis2::ascii::Values
 The numbers of a short reply: ID v1 [v2 ...]. More...
 

Enumerations

enum class  alicat_basis2::ascii::ArgKind : uint8_t {
  alicat_basis2::ascii::ArgKind::None = 0 , alicat_basis2::ascii::ArgKind::Int = 1 , alicat_basis2::ascii::ArgKind::Milli = 2 , alicat_basis2::ascii::ArgKind::Letter = 3 ,
  alicat_basis2::ascii::ArgKind::Star = 4 , alicat_basis2::ascii::ArgKind::Ramp = 5 , alicat_basis2::ascii::ArgKind::IntPair = 6
}
 What a command's argument looks like. More...
 

Functions

constexpr const CommandSpec & alicat_basis2::ascii::Spec (Command c) noexcept
 The row of a command.
 
Result< Request > alicat_basis2::ascii::Make (Command command, char id, const Args &args, bool allow_guarded) noexcept
 Build a request: validate every argument, write the wire bytes.
 
bool alicat_basis2::ascii::IsLegalRequest (std::span< const uint8_t > bytes) noexcept
 Whether bytes is exactly one request of the grammar of M pp.10 to 17: unit ID A to Z, a command with its argument, one CR at the end, only the characters A-Z 0-9 space + - . * @ =.
 
Error alicat_basis2::ascii::Tokenize (std::span< const char > line, Tokens &out) noexcept
 Split a line on runs of spaces.
 
std::span< const char > alicat_basis2::ascii::View (std::span< const char > line, const Token &t) noexcept
 The characters of a token.
 
bool alicat_basis2::ascii::ParseDecimal (std::span< const char > tok, Decimal &out) noexcept
 Parse ‘[+-]? digit{1,12} ( ’.' digit{1,6} )?: no exponent, no hex, nonan`, no leading or trailing point.
 
constexpr char alicat_basis2::ascii::Upper (char c) noexcept
 Upper-case a letter.
 
bool alicat_basis2::ascii::EqualsNoCase (std::span< const char > tok, const char *word) noexcept
 Case-insensitive equality of a token and a word.
 
bool alicat_basis2::ascii::StartsWithId (std::span< const char > line, const Tokens &toks, char id) noexcept
 Whether the first token is exactly one letter equal (any case) to the unit ID.
 
Error alicat_basis2::ascii::DecodeFrame (std::span< const char > line, const FrameRules &rules, Frame &out, FrameLayout &layout_seen) noexcept
 Decode a data frame (C01): ID, three or five numbers, the gas, zero or more flags (M p.10 to 11).
 
Error alicat_basis2::ascii::DecodeData (std::span< const char > line, uint8_t mask, const FrameRules &rules, Frame &out) noexcept
 Decode a DV n reply: ID, then the selected fields in table order (M p.11).
 
Error alicat_basis2::ascii::DecodeValues (std::span< const char > line, char id, uint8_t count, Values &out) noexcept
 Decode ID followed by exactly count numbers.
 
Error alicat_basis2::ascii::DecodeLetter (std::span< const char > line, char id, const char *allowed, char &out) noexcept
 Decode ID x where x is one character out of allowed (case-insensitive).
 
Error alicat_basis2::ascii::DecodeText (std::span< const char > line, char id, Text &out) noexcept
 Decode ID text...: the rest of the line after the ID, truncated to kTextMax characters.
 
Error alicat_basis2::ascii::DecodeGas (std::span< const char > line, char id, Frame &out) noexcept
 Decode a gas reply ID number name (C27, C29).
 
Error alicat_basis2::ascii::DecodeFullScale (std::span< const char > line, char id, FullScale &out) noexcept
 Decode a full-scale reply ID value units (C35).
 
FlowUnit alicat_basis2::ascii::FlowUnitFromLabel (std::span< const char > label) noexcept
 The flow unit of an instrument's label (case-insensitive), Other when it is not one of the twenty.
 
Error alicat_basis2::ascii::DecodeGasList (std::span< const char > line, char id, GasList &out) noexcept
 Decode a gas list ID n name n name ... (C28, A5); sets raw when it does not parse.
 
Error alicat_basis2::ascii::DecodeWindow (std::span< const char > line, char id, uint8_t count, uint32_t &time_ms, Values &out) noexcept
 Decode ID time ... replies of DVAA (two values after the time) and DVAR (four).
 
bool alicat_basis2::ascii::IsErrorToken (std::span< const char > line, char id) noexcept
 Whether a reply line is the error token: ? alone, or ? after the unit ID.
 

Variables

constexpr char alicat_basis2::ascii::kCr = '\r'
 Carriage return, the terminator of every request and reply (M p.10).
 
constexpr std::size_t alicat_basis2::ascii::kCommandRows = 46
 Number of rows of the command table.
 
constexpr int64_t alicat_basis2::ascii::kMilliCap = 999'999'999'999LL
 
constexpr int64_t alicat_basis2::ascii::kMeasureMaxMs = 163'837
 Longest measurement duration in ms the driver sends (derived: 65535 samples of 2.5 ms, A7).
 
constexpr std::array< CommandSpec, kCommandRows > alicat_basis2::ascii::kCommands
 The command table, indexed by Command (data; one row per command of the coverage map).
 
constexpr std::size_t alicat_basis2::ascii::kMaxTokens = 26
 Tokens in a line, at most.
 
constexpr std::size_t alicat_basis2::ascii::kMaxToken = 32
 Longest token, in characters.
 

Detailed Description

Table, encoder, wire validator and decoders.

Enumeration Type Documentation

◆ ArgKind

enum class alicat_basis2::ascii::ArgKind : uint8_t
strong

What a command's argument looks like.

Enumerator
None 

No argument.

Int 

One integer in lo to hi.

Milli 

One decimal number, given in thousandths, in lo to hi.

Letter 

One character out of letters.

Star 

The literal *.

Ramp 

A decimal rate then a time unit 3 to 5.

IntPair 

Two integers, each in lo to hi.

Function Documentation

◆ DecodeData()

Error alicat_basis2::ascii::DecodeData ( std::span< const char >  line,
uint8_t  mask,
const FrameRules &  rules,
Frame &  out 
)
inlinenoexcept

Decode a DV n reply: ID, then the selected fields in table order (M p.11).

Each numeric bit takes one token, the gas one token, and the status the rest: flag tokens, or one unsigned integer equal to the Modbus register 2101 bits (A4).

Parameters
lineThe reply line.
maskThe requested bits, 1 to 255.
rulesThe addressed ID and limits.
outThe frame with present == mask; untouched on failure.
Returns
Ok, DeviceIdMismatch, BadReply or OutOfRange.

◆ DecodeFrame()

Error alicat_basis2::ascii::DecodeFrame ( std::span< const char >  line,
const FrameRules &  rules,
Frame &  out,
FrameLayout &  layout_seen 
)
inlinenoexcept

Decode a data frame (C01): ID, three or five numbers, the gas, zero or more flags (M p.10 to 11).

Parameters
lineThe reply line without its CR.
rulesThe addressed ID, the layout and the plausibility limits.
outThe frame; untouched on failure.
layout_seenThe layout of this frame: Meter or Controller.
Returns
Ok, DeviceIdMismatch, BadReply or OutOfRange.

◆ DecodeFullScale()

Error alicat_basis2::ascii::DecodeFullScale ( std::span< const char >  line,
char  id,
FullScale &  out 
)
inlinenoexcept

Decode a full-scale reply ID value units (C35).

Parameters
lineThe reply line.
idThe addressed ID.
outThe value and unit text.
Returns
Ok, DeviceIdMismatch or BadReply.

◆ DecodeGas()

Error alicat_basis2::ascii::DecodeGas ( std::span< const char >  line,
char  id,
Frame &  out 
)
inlinenoexcept

Decode a gas reply ID number name (C27, C29).

Parameters
lineThe reply line.
idThe addressed ID.
outThe gas; gas_name holds the name.
Returns
Ok, DeviceIdMismatch or BadReply.

◆ DecodeGasList()

Error alicat_basis2::ascii::DecodeGasList ( std::span< const char >  line,
char  id,
GasList &  out 
)
inlinenoexcept

Decode a gas list ID n name n name ... (C28, A5); sets raw when it does not parse.

Parameters
lineThe reply line.
idThe addressed ID.
outThe list, or the raw text.
Returns
Ok (also for raw), DeviceIdMismatch or BadReply (not tokenizable).

◆ DecodeLetter()

Error alicat_basis2::ascii::DecodeLetter ( std::span< const char >  line,
char  id,
const char *  allowed,
char &  out 
)
inlinenoexcept

Decode ID x where x is one character out of allowed (case-insensitive).

Parameters
lineThe reply line.
idThe addressed ID.
allowedUpper-case allowed characters.
outThe character, upper case.
Returns
Ok, DeviceIdMismatch or BadReply.

◆ DecodeText()

Error alicat_basis2::ascii::DecodeText ( std::span< const char >  line,
char  id,
Text &  out 
)
inlinenoexcept

Decode ID text...: the rest of the line after the ID, truncated to kTextMax characters.

Parameters
lineThe reply line.
idThe addressed ID.
outThe text.
Returns
Ok, DeviceIdMismatch or BadReply (no text).

◆ DecodeValues()

Error alicat_basis2::ascii::DecodeValues ( std::span< const char >  line,
char  id,
uint8_t  count,
Values &  out 
)
inlinenoexcept

Decode ID followed by exactly count numbers.

Parameters
lineThe reply line.
idThe addressed ID.
countThe number of values, 1 to 5.
outThe values; untouched on failure.
Returns
Ok, DeviceIdMismatch or BadReply.

◆ DecodeWindow()

Error alicat_basis2::ascii::DecodeWindow ( std::span< const char >  line,
char  id,
uint8_t  count,
uint32_t &  time_ms,
Values &  out 
)
inlinenoexcept

Decode ID time ... replies of DVAA (two values after the time) and DVAR (four).

Parameters
lineThe reply line.
idThe addressed ID.
countValues after the time: 2 or 4.
time_msThe time in ms.
outThe values.
Returns
Ok, DeviceIdMismatch or BadReply.

◆ EqualsNoCase()

bool alicat_basis2::ascii::EqualsNoCase ( std::span< const char >  tok,
const char *  word 
)
inlinenoexcept

Case-insensitive equality of a token and a word.

Parameters
tokThe token.
wordNUL-terminated word.
Returns
true when equal.

◆ FlowUnitFromLabel()

FlowUnit alicat_basis2::ascii::FlowUnitFromLabel ( std::span< const char >  label)
inlinenoexcept

The flow unit of an instrument's label (case-insensitive), Other when it is not one of the twenty.

Parameters
labelThe label text.
Returns
The unit.

◆ IsErrorToken()

bool alicat_basis2::ascii::IsErrorToken ( std::span< const char >  line,
char  id 
)
inlinenoexcept

Whether a reply line is the error token: ? alone, or ? after the unit ID.

Parameters
lineThe line.
idThe addressed ID.
Returns
true when it is.

◆ IsLegalRequest()

bool alicat_basis2::ascii::IsLegalRequest ( std::span< const uint8_t >  bytes)
inlinenoexcept

Whether bytes is exactly one request of the grammar of M pp.10 to 17: unit ID A to Z, a command with its argument, one CR at the end, only the characters A-Z 0-9 space + - . * @ =.

Hand-written and independent of kCommands: a mismatch between the table and this function is a build failure of tests/test_grammar.cpp. The driver runs it before every Write().

Parameters
bytesThe candidate wire bytes.
Returns
true when it is a legal request.

◆ Make()

Result< Request > alicat_basis2::ascii::Make ( Command  command,
char  id,
const Args &  args,
bool  allow_guarded 
)
inlinenoexcept

Build a request: validate every argument, write the wire bytes.

Guarded rows are built only when allow_guarded is true; the public guarded calls of Basis2 pass it after checking their token. A rejected argument returns InvalidArgument and nothing is formed.

Parameters
commandAn ASCII command.
idThe unit ID, A to Z.
argsThe arguments.
allow_guardedWhether a guarded row may be built.
Returns
The request, or InvalidArgument (also for Command::Modbus).

◆ ParseDecimal()

bool alicat_basis2::ascii::ParseDecimal ( std::span< const char >  tok,
Decimal &  out 
)
inlinenoexcept

Parse ‘[+-]? digit{1,12} ( ’.' digit{1,6} )?: no exponent, no hex, nonan`, no leading or trailing point.

Parameters
tokThe token's characters.
outThe number, with the decimal count of the text preserved.
Returns
true when the whole token is a number.

◆ Spec()

constexpr const CommandSpec & alicat_basis2::ascii::Spec ( Command  c)
constexprnoexcept

The row of a command.

Parameters
cAn ASCII command (not Command::Modbus).
Returns
The row; the first row for Command::Modbus.

◆ StartsWithId()

bool alicat_basis2::ascii::StartsWithId ( std::span< const char >  line,
const Tokens &  toks,
char  id 
)
inlinenoexcept

Whether the first token is exactly one letter equal (any case) to the unit ID.

Parameters
lineThe line.
toksIts tokens.
idThe addressed ID, upper case.
Returns
true when it is.

◆ Tokenize()

Error alicat_basis2::ascii::Tokenize ( std::span< const char >  line,
Tokens &  out 
)
inlinenoexcept

Split a line on runs of spaces.

Parameters
lineThe line without its CR.
outThe tokens.
Returns
Ok, or BadReply for a character outside 0x21 to 0x7E (other than the space), a token over kMaxToken characters, more than kMaxTokens tokens, or an empty line.

◆ Upper()

constexpr char alicat_basis2::ascii::Upper ( char  c)
constexprnoexcept

Upper-case a letter.

Parameters
cThe character.
Returns
c, upper-cased when it is a letter.

◆ View()

std::span< const char > alicat_basis2::ascii::View ( std::span< const char >  line,
const Token &  t 
)
inlinenoexcept

The characters of a token.

Parameters
lineThe line.
tThe token.
Returns
A view of the token's characters.

Variable Documentation

◆ kMilliCap

constexpr int64_t alicat_basis2::ascii::kMilliCap = 999'999'999'999LL
inlineconstexpr

Upper bound of a decimal argument in thousandths (10^12: below the mantissa limit of the parser).