TBMANLIB Package

Author: woeoio. On GitHub: woeoio/tbman, the repository of the TBMAN toolkit. Its first commit, of 7 December 2024, the day this version was published, holds the code of this package. The repository has been developed since, and its current code differs from version 1.0.0.5.

The TBMANLIB contributed package is the library of TBMAN, a toolkit for twinBASIC programmers that grew out of the author’s VB6 library vbman. It is a collection of small helpers rather than a library with one theme: a JSON document class and parser, a log writer, a stopwatch, an INI file class, a message-box helper, and modules of functions for strings, arrays and bytes, UTF-8, dictionaries, files and folders, numbers and JavaScript objects. The package’s own description on TWINSERV is the single word TBMAN.

Dim J As New cJson
Dim UserName As String
J.Decode "{""user"":{""name"":""Ann""},""scores"":[3,5]}"

UserName = J.Item("user")("name")
Debug.Print UserName
Debug.Print J.Item("scores")(2)
Debug.Print ToolsStr.InsertSpan(UserName, "-", 1)
Debug.Print J.Encode()
' Output:
' Ann
' 5
' A-n-n
' {"user":{"name":"Ann"},"scores":[3,5]}

What the package offers

  • JSON. cJson holds a JSON document: it reads a text or a file, gives access to its objects and arrays, builds new ones, and writes them as text or to a file. The parser and writer are the code of VBA-JSON, in ToolsJsonVba.
  • Logs. cLogs writes log lines to files in a folder tree by day or month, and can send each line to a list box, to a debugging tool or to a web page, with four levels.
  • Time. cTimeuse is a stopwatch with a millisecond count.
  • Messages. cLayer shows a message box.
  • INI files. cCsv, in spite of its name, reads and writes INI files.
  • Text and bytes. ToolsStr trims, cuts and searches strings, makes %XX and \uXXXX escapes, converts between strings and bytes, and makes random strings and GUIDs. ToolsArray finds, slices and splits byte arrays. ToolsUtf8 converts between UTF-8 bytes and strings. ToolsMath rounds up and picks random numbers.
  • Files and folders. ToolsFso completes paths and creates folders. ToolsStream reads and writes whole files as text in a chosen character set or as bytes.
  • Dictionaries and JavaScript. ToolsDic reads and writes form text, merges and copies Scripting.Dictionary objects. ToolsJScript creates JavaScript arrays and objects with the Microsoft Script Control.
  • Ready-made instances. The module TBMAN has one shared instance of each class, so a program can write TBMAN.Json or TBMAN.Logs without New.

The classes are created with New, as in Dim J As New cJson. The members of a module are called with the name of the module in front, as in ToolsStr.TrimEx(...). The names of the package’s own members keep the author’s spelling, including the misspellings, such as DebugPring, LogFileNameByUer and TowLevelDicAssign; this documentation uses them as they are.

Components the package uses

The package is written on top of components that are not part of twinBASIC. Its references are the Microsoft Scripting Runtime, the Microsoft ActiveX Data Objects 2.8 library and the Microsoft Script Control 1.0, and some members create other objects by name.

Component Used by
Scripting Runtime: Scripting.Dictionary cJson (RootItem), cCsv (Root), ToolsDic, ToolsJsonVba
Scripting Runtime: Scripting.FileSystemObject cCsv, ToolsFso
ActiveX Data Objects: ADODB.Stream ToolsStream, so cJson.LoadFrom and cJson.SaveTo
Microsoft Script Control: MSScriptControl.ScriptControl ToolsJScript, so ToolsDic.ToWwwFormUrlencoded
WinHttp.WinHttpRequest.5.1, created by name cLogs.WebView
Scriptlet.TypeLib, created by name ToolsStr.GetGUID
imagehlp.dll (MakeSureDirectoryPathExists) cLogs.Save, ToolsFso.AutoMakeDir
kernel32.dll (GetTickCount, OutputDebugStringA, RtlMoveMemory, MultiByteToWideChar, WideCharToMultiByte) cTimeuse, cLogs.DbgView, ToolsArray, ToolsUtf8

The references of a package are not visible to the project that uses it. A program that names a type of these libraries in its own code, such as Dim D As New Scripting.Dictionary, adds the library to its own references; in a project that references only TBMANLIB the compiler refuses the name with TB5079, Unrecognized datatype symbol ‘Scripting’. A program can call members that return those objects without naming the type, for example J.Item("user")("name"), and can create an object by name with CreateObject.

32-bit and 64-bit programs

The Microsoft Script Control exists only as a 32-bit component, and the package’s reference to it has a path for 32-bit programs and none for 64-bit programs.

The Script Control is used by ToolsJScript and, through it, by ToolsDic.ToWwwFormUrlencoded. Those members do not work in 32-bit programs either; see ToolsJScript. The other components are available to 32-bit programs.

Defects of version 1.0.0.5

Part of the code is unfinished, and the source holds test code and notes to the author. Where a member does not do what its name or comment says, the page of the member says so. The ones that matter most are these:

Classes

  • cCsv – reads and writes INI files into a two-level dictionary.
  • cJson – holds a JSON document: reads and writes text and files, and builds objects and arrays.
  • cLayer – shows a message box.
  • cLogs – writes log lines to files and to other outputs, with levels.
  • cTimeuse – a stopwatch in milliseconds.

Modules

  • TBMAN – shared instances of the classes, and a version text.
  • ToolsArray – finds, slices and splits arrays of bytes and longs.
  • ToolsDic – form text, merging and copying of dictionaries.
  • ToolsFso – completes paths, tidies slashes and creates folders.
  • ToolsJScript – creates JavaScript arrays and objects with the Script Control.
  • ToolsJsonVba – the VBA-JSON parser and writer, and the VBA-UTC date functions.
  • ToolsMath – rounds up, and picks random whole numbers.
  • ToolsStr – trims, searches, escapes and converts strings; random text and GUIDs.
  • ToolsStream – reads and writes whole files as text or bytes.
  • ToolsUtf8 – converts between UTF-8 bytes and strings.

Types without members

Three types of the package have no members, and have no page: cIni, cTimer and ToolsJsonUcs. Each holds only the comment add your member fields and procedures here, or, for ToolsJsonUcs, add your procedures here. cIni is the type of TBMAN.Ini and the declared result of cCsv.LoadFrom.

See Also