100% found this document useful (1 vote)

9 views

Language Server Protocol and Implementation: Supporting Language-Smart Editing and Programming Tools 1st Edition Nadeeshaan Gunasinghe - The full ebook set is available with all chapters for download

The document provides information about the book 'Language Server Protocol and Implementation: Supporting Language-Smart Editing and Programming Tools' by Nadeeshaan Gunasinghe and Nipuna Marcus. It includes details on various programming tools, the Language Server Protocol, and its implementation, along with a table of contents outlining the chapters and topics covered. Additionally, it offers links to various other eBooks available for instant download on ebookmeta.com.

Uploaded by

kophyputnam

Available Formats

Download as PDF, TXT or read online on Scribd

100% found this document useful (1 vote)

9 views

Language Server Protocol and Implementation: Supporting Language-Smart Editing and Programming Tools 1st Edition Nadeeshaan Gunasinghe - The full ebook set is available with all chapters for download

Uploaded by

kophyputnam

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 75

Read Anytime Anywhere Easy Ebook Downloads at ebookmeta.

com

Language Server Protocol and Implementation:

Supporting Language-Smart Editing and Programming
Tools 1st Edition Nadeeshaan Gunasinghe

https://ebookmeta.com/product/language-server-protocol-and-
implementation-supporting-language-smart-editing-and-
programming-tools-1st-edition-nadeeshaan-gunasinghe/

OR CLICK HERE

DOWLOAD EBOOK

Visit and Get More Ebook Downloads Instantly at https://ebookmeta.com

Recommended digital products (PDF, EPUB, MOBI) that
you can download immediately if you are interested.

Supporting Adolescents with Language Disorders 1st Edition

Sarah Spencer

https://ebookmeta.com/product/supporting-adolescents-with-language-
disorders-1st-edition-sarah-spencer/

ebookmeta.com

The Rust Programming Language Steve Klabnik

https://ebookmeta.com/product/the-rust-programming-language-steve-
klabnik/

ebookmeta.com

Modern Parallel Programming with C++ and Assembly Language

Daniel Kusswurm

https://ebookmeta.com/product/modern-parallel-programming-with-c-and-
assembly-language-daniel-kusswurm/

ebookmeta.com

Etched in Bone The Others 05 First Edition Anne Bishop

https://ebookmeta.com/product/etched-in-bone-the-others-05-first-
edition-anne-bishop/

ebookmeta.com
Leonardo s Art Workshop Invent Create and Make STEAM
Projects like a Genius Amy Leidtke

https://ebookmeta.com/product/leonardo-s-art-workshop-invent-create-
and-make-steam-projects-like-a-genius-amy-leidtke/

ebookmeta.com

Autonomous Underwater Vehicles: Localization, Tracking,

and Formation (Cognitive Intelligence and Robotics) Yan

https://ebookmeta.com/product/autonomous-underwater-vehicles-
localization-tracking-and-formation-cognitive-intelligence-and-
robotics-yan/
ebookmeta.com

Sealy and Hooley's Commercial Law 6th edition David Fox

https://ebookmeta.com/product/sealy-and-hooleys-commercial-law-6th-
edition-david-fox/

ebookmeta.com

Fodor's San Antonio, Austin & the Texas Hill Country 2nd
Edition Fodor'S Travel Guides

https://ebookmeta.com/product/fodors-san-antonio-austin-the-texas-
hill-country-2nd-edition-fodors-travel-guides/

ebookmeta.com

Bioinoculants Biological Option for Mitigating global

Climate Change Surender Singh (Editor)

https://ebookmeta.com/product/bioinoculants-biological-option-for-
mitigating-global-climate-change-surender-singh-editor/

ebookmeta.com
Troubleshooting and Maintaining PCs All in One For Dummies
Dan Gookin

https://ebookmeta.com/product/troubleshooting-and-maintaining-pcs-all-
in-one-for-dummies-dan-gookin/

ebookmeta.com
Language Server
Protocol and
Implementation
Supporting Language-Smart Editing and
Programming Tools
—
Nadeeshaan Gunasinghe
Nipuna Marcus
Language Server Protocol
and Implementation
Supporting Language-Smart
Editing and Programming Tools

Nadeeshaan Gunasinghe
Nipuna Marcus
Language Server Protocol and Implementation: Supporting Language-Smart Editing
and Programming Tools
Nadeeshaan Gunasinghe Nipuna Marcus
Walahanduwa, Sri Lanka Mawathagama, Sri Lanka

ISBN-13 (pbk): 978-1-4842-7791-1 ISBN-13 (electronic): 978-1-4842-7792-8

https://doi.org/10.1007/978-1-4842-7792-8

Copyright © 2022 by Nadeeshaan Gunasinghe and Nipuna Marcus

This work is subject to copyright. All rights are reserved by the Publisher, whether the whole or part of the
material is concerned, specifically the rights of translation, reprinting, reuse of illustrations, recitation,
broadcasting, reproduction on microfilms or in any other physical way, and transmission or information
storage and retrieval, electronic adaptation, computer software, or by similar or dissimilar methodology now
known or hereafter developed.
Trademarked names, logos, and images may appear in this book. Rather than use a trademark symbol with
every occurrence of a trademarked name, logo, or image we use the names, logos, and images only in an
editorial fashion and to the benefit of the trademark owner, with no intention of infringement of the
trademark.
The use in this publication of trade names, trademarks, service marks, and similar terms, even if they are not
identified as such, is not to be taken as an expression of opinion as to whether or not they are subject to
proprietary rights.
While the advice and information in this book are believed to be true and accurate at the date of publication,
neither the authors nor the editors nor the publisher can accept any legal responsibility for any errors or
omissions that may be made. The publisher makes no warranty, express or implied, with respect to the
material contained herein.
Managing Director, Apress Media LLC: Welmoed Spahr
Acquisitions Editor: Jonathan Gennick
Development Editor: Laura Berendson
Coordinating Editor: Jill Balzano
Cover designed by eStudioCalamar
Cover image designed by Freepik (www.freepik.com)
Distributed to the book trade worldwide by Springer Science+Business Media New York, 1 New York Plaza,
Suite 4600, New York, NY 10004-1562, USA. Phone 1-800-SPRINGER, fax (201) 348-4505, e-mail orders-ny@
springer-sbm.com, or visit www.springeronline.com. Apress Media, LLC is a California LLC and the sole
member (owner) is Springer Science + Business Media Finance Inc (SSBM Finance Inc). SSBM Finance Inc
is a Delaware corporation.
For information on translations, please e-mail [email protected]; for reprint,
paperback, or audio rights, please e-mail [email protected].
Apress titles may be purchased in bulk for academic, corporate, or promotional use. eBook versions and
licenses are also available for most titles. For more information, reference our Print and eBook Bulk Sales
web page at http://www.apress.com/bulk-sales.
Any source code or other supplementary material referenced by the author in this book is available to
readers on GitHub via the book’s product page, located at www.apress.com/978-1-4842-7791-1. For more
detailed information, please visit http://www.apress.com/source-code.
Printed on acid-free paper
To our beloved parents who always were behind us and
Kasun Indrasiri who always was an inspiration and
a role model
Table of Contents
About the Authors��xv

About the Technical Reviewer��xvii

Acknowledgments��xix

Introduction��xxi

Chapter 1: Developer Tools and Language Services�� 1

Early Programmable Computers�� 1
Code Forms and Punched Cards�� 2
Text Editors vs. Source Code Editors�� 3
Why IDEs�� 5
Language Intelligence�� 7
Summary�� 9

Chapter 2: Understanding the Language Server Protocol�� 11

Understanding JSON-RPC�� 13
Request Object�� 13
Response Object�� 15
Batch�� 17
Understanding the Base Protocol�� 18
Header Part�� 18
Content Part�� 18
Communication Model�� 19
General Messages�� 20
$/�� 20
window�� 20
telemetry�� 21

v
Table of Contents

workspace�� 21
textDocument�� 21
Summary�� 22

Chapter 3: Implementing a Language Server�� 23

Tools and Dependencies�� 24
Building the Project�� 25
Compatibility with Ballerina�� 27
Debugging the Client and the Server�� 27
Understanding the Main Components�� 27
Server API�� 28
Server Core�� 31
Client Implementation�� 33
Summary�� 33

Chapter 4: General Messages�� 35

General Messages�� 35
Initialize�� 35
Initialized�� 43
Shutdown�� 43
Exit�� 44
Window Operations�� 45
ShowMessage�� 45
ShowMessageRequest�� 46
ShowDocument�� 48
LogMessage�� 48
Progress/Create�� 49
Progress/Cancel�� 49
Summary�� 50

vi
Table of Contents

Chapter 5: Text Synchronization�� 51

General Capabilities�� 52
didOpen�� 53
Indexing and Project Initialization�� 55
didChange�� 56
willSave�� 59
willSaveWaitUntil�� 60
didSave�� 61
didClose�� 62
Summary�� 63

Chapter 6: Diagnostics, Smart Editing, and Documentation�� 65

Diagnostics�� 65
Initialization and Capabilities�� 65
Publishing the Diagnostics�� 67
Completion�� 72
Initialization and Capabilities�� 72
Completion Resolve�� 89
Signature Help�� 92
Initialization and Capabilities�� 92
Hover�� 97
Initialization and Capabilities�� 97
Generating the Hover�� 97
Summary�� 100

Chapter 7: Refactoring and Code Fixes�� 101

Rename�� 101
Initialization and Capabilities�� 102
Generating the Workspace Edit�� 103
Prepare Rename�� 107

vii
Table of Contents

Formatting�� 109
Initialization and Capabilities�� 109
Generating the Formatting TextEdits�� 110
Range Formatting�� 111
Initialization and Capabilities�� 112
Generating the Range Formatting TextEdits�� 112
On Type Formatting�� 114
Initialization and Capabilities�� 114
Generating the On Type Formatting TextEdits�� 115
Code Actions�� 117
Initialization and Capabilities�� 118
Generating the CodeAction�� 120
Code Actions Resolve�� 125
CodeLens�� 126
Initialization and Capabilities�� 126
Generating the Response�� 127
CodeLens Resolve�� 128
CodeLens Refresh�� 128
Summary�� 129

Chapter 8: Code Navigation and Navigation Helpers�� 131

Reference�� 131
Client Capabilities�� 132
Server Capabilities�� 132
Generating the Response�� 132
Definition�� 134
Client Capabilities�� 134
Server Capabilities�� 135
Generating the Response�� 135

viii
Table of Contents

Type Definition�� 138

Client Capabilities�� 139
Server Capabilities�� 139
Generating the Response�� 140
Implementation�� 141
Client Capabilities�� 142
Server Capabilities�� 142
Generating the Response�� 142
Declaration�� 143
Client Capabilities�� 143
Server Capabilities�� 143
Generating the Response�� 144
Document Symbol�� 144
Client Capabilities�� 144
Server Capabilities�� 145
Generating the Response�� 146
Document Highlight�� 150
Client Capabilities�� 150
Server Capabilities�� 150
Generating the Response�� 151
Document Link�� 153
Client Capabilities�� 153
Server Capabilities�� 153
Generating the Response�� 153
Document Link Resolve�� 155
Summary�� 156

ix
Table of Contents

Chapter 9: Presentation and Selection�� 157

Semantic Tokens�� 157
Client Capabilities�� 159
Server Capabilities�� 159
Generating the Response�� 160
Document Color�� 165
Client Capabilities�� 165
Server Capabilities�� 165
Generating the Response�� 165
Color Presentation�� 167
Generating the Response�� 168
Folding Range�� 169
Client Capabilities�� 170
Server Capabilities�� 170
Generating the Response�� 170
Selection Range�� 172
Client Capabilities�� 172
Server Capabilities�� 172
Generating the Response�� 172
Linked Editing Range�� 174
Client Capabilities�� 174
Server Capabilities�� 174
Generating the Response�� 174
Prepare Call Hierarchy�� 176
Client Capabilities�� 176
Server Capabilities�� 176
Generating the Response�� 177
Call Hierarchy Incoming�� 178
Generating the Response�� 179

x
Table of Contents

Call Hierarchy Outgoing�� 180

Generating the Response�� 180
Summary�� 181

Chapter 10: Workspace Operations�� 183

Workspace Folders�� 184
Client Capabilities�� 184
Server Capabilities�� 184
Sending the Request�� 185
Workspace Folders Change Notification�� 185
Client Capabilities�� 186
Server Capabilities�� 186
Processing the Notification�� 186
Notification of Configuration Change�� 187
Client Capabilities�� 188
Processing the Notification�� 188
Configuration�� 191
Client Capabilities�� 191
Generating the Request�� 191
Watched Files Change Notification�� 192
Client Capabilities�� 193
Registration Options�� 193
Processing the Notification�� 194
Workspace Symbol�� 196
Client Capabilities�� 196
Server Capabilities and Registration Options�� 197
Generating the Response�� 197
Execute Command�� 199
Client Capabilities�� 199
Server Capabilities�� 199
Executing the Command�� 200

xi
Table of Contents

Apply Edit�� 200

Client Capabilities�� 201
Sending the Request�� 202
Will Create Files�� 203
Client Capabilities�� 204
Registration Options�� 204
Generating the Response�� 204
Did Create Files�� 205
Client Capabilities�� 205
Server Capabilities�� 205
Handling the Notification�� 205
Will Rename Files�� 205
Client Capabilities�� 206
Server Capabilities�� 206
Generating the Response�� 206
Did Rename Files�� 206
Client Capabilities�� 206
Server Capabilities�� 207
Handling the Notification�� 207
Will Delete Files�� 207
Client Capabilities�� 207
Server Capabilities�� 207
Generating the Response�� 208
Deleted Files Notification�� 208
Client Capabilities�� 208
Server Capabilities�� 208
Handling the Notification�� 208
Summary�� 209

xii
Table of Contents

Chapter 11: Advanced Concepts�� 211

Work Done Progress�� 211
Begin Progress�� 214
Report Progress�� 215
End Progress�� 215
Implementing the Server-Initiated Progress�� 215
Partial Result Support�� 218
Working with Launchers�� 218
Extension Points�� 223
Implementing and Extending Protocol Services�� 223
Supporting Multiple Languages�� 226
Summary�� 230

Index�� 233

xiii
About the Authors
Nadeeshaan Gunasinghe is Technical Lead at WSO2
and has more than five years of experience in enterprise
integration, programming languages, and developer
tooling. He leads the Ballerina Language Server team and
is a key contributor to Ballerina, which is an open source
programming language and platform for the cloud, and he is
an active contributor to the WSO2 Enterprise Service Bus.

Nipuna Marcus is Technical Lead at WSO2 and has more

than five years of experience in front-end development,
programming languages, and developer tooling. He was a
member of the Ballerina Language Server team and a key
contributor to the Ballerina programming language.

xv
About the Technical Reviewer
Andres Sacco has been working as a developer since
2007 in different languages including Java, PHP, Node.js,
and Android. Most of his background is in Java and the
libraries or frameworks associated with this language, for
example, Spring, Hibernate, JSF, and Quarkus. In most
of the companies that he worked for, he researched new
technologies in order to improve the performance, stability,
and quality of the applications of each company.

xvii
Acknowledgments
We would first like to thank Jonathan Gennick, Assistant Editorial Director at Apress, for
evaluating and accepting our proposal for this book. We would also like to thank Laura
Berendson, Development Editor at Apress, and Nirmal Selvaraj, Project Coordinator, for
guiding us toward the end. Andres Sacco served as the Technical Reviewer. Thank you,
Andres, for making sure we did our best.
Kasun Indrasiri, Software Architect and author of Microservices for the Enterprise and
GRPC: Up and Running, inspired us to work on this book and mentored us throughout
the process. We are eternally grateful to Kasun Indrasiri for the guidance and support.
Finally, we would like to thank our families and parents as, without them, none of
our life achievements would be possible.

xix
Introduction
The Language Server Protocol (LSP) has been one of the most talked about topics during
the past few years when it comes to the tooling for programming languages. With the
advancement of the developer tools and the programming languages, developers started
to rely more and more on advanced tools and enhanced language services. When we
consider one of the most focused branches of developer tools which is IDEs and text
editors, there are many vendors who have released various editing tools in the past
couple of decades. When we consider the number of programming languages along with
the number of smart editors nowadays, in order to support language intelligence among
the editors, these vendors have to repeat the same thing. The Language Server Protocol
was introduced to solve this particular problem, and today it has become the norm of
the development tools’ language intelligence provider. By adopting the LSP, tools such
as text editors and integrated development environments (IDEs) could expand the
capabilities and avoid the users’ burden of switching between the development tools for
trying new programming languages and frameworks.
This book is for the developers who are passionate about developing programming
language tools. In this book, we provide the readers a comprehensive understanding
about the Language Server Protocol and how to develop a Language Server from scratch.
The readers will be guided with code samples to provide a better understanding about
the server implementation by adhering to the user experience best practices as well as
the LSP best practices. The readers are expected to use the book along with the example
implementation, in order to get a better understanding about the concepts described
in the book. In the example implementation, the book refers to VS Code as the client;
however, the readers can use any other client and integrate the server implementation as
desired.
The chapters of the book have been ordered to capture various aspects of the
developer experience when it comes to the programming language tooling, and the
LSP operations and features are categorized under these aspects. The readers are not
overwhelmed by including the code snippets of the data structures in the LSP and it is
recommended to refer to the official documentation of the Language Server Protocol for
the data structures.

xxi
CHAPTER 1

Developer Tools
and Language Services
Today, software development has become an area where there are higher expectations
when considering the rapid development, go-to market, deployment, distribution, and
similar aspects. In this book, we are going to focus on a specific technical perspective
related to source code editing or, in other words, writing the software.

Early Programmable Computers

Decades before the golden age of digital computers, it all began with mechanical
computers. Even though today computers can carry out various tasks, early
mechanical computers could carry out a specific task. Among them, one of the most
important programmable machines developed was the Jacquard loom. Jacquard
loom’s idea of programming the machinery was later inspired by other programmable
inventions as well.
Joseph-Marie Jacquard invented the Jacquard loom1 in 1804. The Jacquard loom was
programmed by using punched cards. Different weaving patterns could be programmed
by using punched cards, and the loom was automated on top of the program. Therefore,
the Jacquard loom is considered the first programmable machine, and the concept of
punched cards was adopted later by both Babbage as well as digital computers.
In the history of mechanical computers, the Analytical Engine developed by
Charles Babbage2 can be considered as the earliest mechanical computer. Input data
was fed to the machine by means of punched cards which were used in the Jacquard

1
www.columbia.edu/cu/computinghistory/jacquard.html
2
www.computerhistory.org/babbage/
1
© Nadeeshaan Gunasinghe and Nipuna Marcus 2022
N. Gunasinghe and N. Marcus, Language Server Protocol and Implementation,
https://doi.org/10.1007/978-1-4842-7792-8_1
Chapter 1 Developer Tools and Language Services

programmable loom. One of the most important aspects of the Analytical Engine is the
ability to program the engine by changing the instructions on punched cards.
In both of the aforementioned examples, the medium of programming the
computers was using punched cards. Not only mechanical computers but also early
digital age computers used punched cards to input programs to the computer and store
data. For example, if we consider computers such as IBM 360, it was the punched cards
that were used to write the programs.

Code Forms and Punched Cards

For instance, let’s compare how we write our programs with a programming language
today with the punched card era.3 Have you ever wondered that it might have taken
hours to write a program, run it, and see the output? Have you ever tried to write a
program on a piece of paper? Imagine how tedious that would be to develop even
a simple “Hello world!” in such a manner? Decades before today, this is how even
professional programmers used to write their programs. As briefly described in the
previous section, in early days punched cards were used to store data and programs, and
those cards were fed into the computer for execution. Keypunching your program to the
punched card in a single run is not an easy task. Therefore, another technique called
code sheets, also known as coding forms, was used. The programmers had to write
their programs’ instructions on the code sheets at first. Then they had to convert these
instructions to a form which can be identified by the computers.
Computers could identify and process the instructions fed in the form of punched
cards. A punched card operator keypunches the instructions onto the punched cards to
insert them into the computer to run. If there is an error or a bug, you have to follow the
same routine again and again to fix it.
Now consider a program with a number of statements and the cycle of writing,
running, and fixing issues. Each time, you will get a stack of punched cards where the
program is embedded into. This is the amount of work that had to be done decades ago
in order to write even a simple "Hello World" program.

3
www.columbia.edu/cu/computinghistory/fisk.pdf

2
Chapter 1 Developer Tools and Language Services

Text Editors vs. Source Code Editors

With the advancement of technology, programmers started using various tools for
writing their codes with convenience. Among these tools, text-based editors have
become more popular than other options. Even though text-based tools are more
popular than the others, there are other tools such as visual programming editors which
allow users to write their code with graphic components. Developers can drag and drop
high-level graphical constructs/basic programming constructs to build the program,
and the editor auto-generates the textual code on behalf of the user. Google’s Blockly is a
library which allows building visual programming editors. Also, programming languages
such as Prograph and visual programming environments such as Cantata4 can be
considered as tools for visual programming.
Today, when editing source codes, there are various editing tools to be chosen
among. The most common choice would be a source editor, text editor, or an IDE. In
one aspect, all the aforementioned choices are similar, in that all those options support
text editing. But, those are completely three different tools when it comes to the editing
experience. Most of the time, there is a misconception to consider that source code
editors and text editors are the same even though they are not. Text editors, as the name
implies, are used for editing textual content and can also be used for composing and
editing source codes. Source code editors on the other hand have language sensitivity
and context awareness. There are certain features incorporated into source code
editors which represent language sensitivity and context awareness. Among them,
auto-completion, syntax highlighting, and intelligent refactoring options such as source
formatting can be shown as the most commonly used features.
Before the origin of graphical user interfaces (GUIs), command-line interface
(CLI)–based text editors were popular among the developers. While CLI-based editors
are command driven, GUI-based editors are menu driven. Even though GUI-based
editors became popular, people continued to use CLI-based editors even today. Also,
having certain expertise in using a CLI-based editor is a must when you get to work
in an environment without a GUI such as a server. Today, we can install plugins and
extensions for text editors, and we can convert them to behave similarly to source code
editors. One such example is the Vim editor, where you can install various plugins for
formatting and auto-completion for JavaScript development.5

4
https://dl.acm.org/doi/abs/10.1145/204362.204367
5
https://vimawesome.com/plugin/vim-javascript

3
Chapter 1 Developer Tools and Language Services

Some examples of text-based editing tools are as follows:

• Vi

• Vim6

• Emacs7

• Notepad++8

• Visual Studio Code (VS Code9)

• NetBeans10

• Eclipse11

• IntelliJ IDEA12

This is just a small sample of editors among numerous available options.

These various editors can be categorized based on multiple factors, such as

• Language support (multi-language or specific language support)

IDEs such as IntelliJ IDEA, Eclipse, and VS Code support multiple

programming languages allowing the user to install plugins and
extensions. When the Java ecosystem is considered, IntelliJ IDEA
and Eclipse are the popular choices among the developers.

• Hosting environment (cloud hosted or locally hosted)

IDEs such as Codenvy, JSFiddle, and CodePen are popular cloud-

hosted IDEs. CodePen and JSFiddle have become the most widely
used IDE solutions to share working code examples.

6
www.vim.org/download.php
7
www.gnu.org/software/emacs/
8
https://notepad-plus-plus.org/
9
https://code.visualstudio.com/
10
https://netbeans.apache.org/
11
www.eclipse.org/downloads/
12
www.jetbrains.com/idea/download/

4
Chapter 1 Developer Tools and Language Services

• Development type oriented (web development/mobile

development/DevOps)

Android Studio is the official IDE by Google for Android

development which is built on IntelliJ IDEA. If we consider
tools such as Vi and Vim, they are widely used when it comes to
DevOps tasks such as server configurations.

• Extensibility and plugin support

Users can install plugins to the VS Code editor and expand the
default capabilities. For example, the VS Code marketplace has
plugins for numerous programming languages.

Given the aforementioned categorization, if we consider the JVM ecosystem,

the most widely used IDE is IntelliJ IDEA, while text editors such as VS Code and Vi/Vim
have a lesser usage.13 Even though we consider the JVM ecosystem here, according to
the Stack Overflow Developer Survey (2021),14 VS Code is the most commonly used text
editor among the developers.

W
hy IDEs
Source code editing is not the only phase in the software development life cycle, which
consists of a number of phases as well as associated supporting steps. In each of these
steps, the stakeholders use various tools to facilitate these phases. Several such tools can
be listed as follows:
• Diagramming tools (for use case identification, ER diagrams15)
• Source code editors (Notepad++, Vim)

• Version control systems (Git,16 SVN17)

13
https://res.cloudinary.com/snyk/image/upload/v1623860216/reports/jvm-ecosystem-
report-2021.pdf
14
https://insights.stackoverflow.com/survey/2021#integrated-development-environment
15
https://staruml.io/
16
https://docs.github.com/en/get-started
17
https://subversion.apache.org/

5
Chapter 1 Developer Tools and Language Services

• Debuggers (JSwat18)

• Coverage tools (JaCoCo19)

• Code search tools (Sourcegraph20)

• Linters (Checkstyle21)

• Issue trackers

• DevOps tools

• And so on

Among these tools, we can identify categories, and during the last couple of decades,
various platforms and products were introduced focusing on specific categories.
When we consider the IDEs, they put numerous features together. Therefore, we
can identify IDEs as an all-in-one package for a developer. This is one reason for IDEs
becoming popular over time when compared to text editors. Among the incorporated
features in IDEs, the following can be identified as the most widely used ones:

• Context-aware auto-completions (smart completions)

• Source refactoring options (rename references, formatting)

• Code search options (for Java, class and method search)

• Run and debug

• Code coverage

• Integrated version controlling (Git integration and SVN)

18
https://github.com/nlfiedler/jswat
19
www.eclemma.org/jacoco/
20
https://about.sourcegraph.com/
21
https://checkstyle.sourceforge.io/config_design.html

6
Chapter 1 Developer Tools and Language Services

L anguage Intelligence
In the previous sections, we had a look at the various options available for source code
editing. Whether it is a text editor, a source code editor, or an IDE, all of those tools have
a common underlying competency to be aware of the language syntax and semantics; we
call it language intelligence. Let’s consider an example usage of an IDE for programming.
There are numerous language-sensitive features a user uses during coding.
One of the most frequently used language intelligence features is diagnostics.
For example, consider writing Java code with a missing semicolon (syntax error) and
compile it. Then the compiler will stop in the middle of compilation, and the console will
show the problems in the source. Listing 1-1 is an example of an erroneous Java source
where there is a missing semicolon. You can copy and paste the sample code snippet in
your favorite source code editor and observe how the editor represents these errors to
the developer.

Listing 1-1. Invalid Java Source with a Missing Semicolon

public class Greeting {

    public static void main(String[] args) {
        // Semicolon is missing in print statement
        System.out.println("Hello World")
    }
}

As an exercise, you can select more than one IDE/source editor and observe the
diagnostic representations in those. Depending on the tool, the representation of the
diagnostics can be different. Figure 1-1 is an example of the diagnostic representation for
the preceding erroneous source snippet.

7
Chapter 1 Developer Tools and Language Services

Figure 1-1. Showing diagnostics for Java in IntelliJ IDEA

When it comes to the IDEs/editors for source code editing, it is important to show
the syntax or semantic errors on the fly. In order to implement the diagnostics for a
particular programming language or even a configuration language such as Swagger,22
the IDE or tooling developer needs to map the compiler’s knowledge to the tooling APIs
preserving the user experience.
We had a look at the diagnostics since it is one of the basic language intelligence
features. Similar to the diagnostics, other features such as smart completions, refactoring
(rename and formatting), code navigation, etc., play a major role in the development
experience. Therefore, every developer tooling vendor pays considerable attention
to language intelligence features integrated with the tools. With time, these language
features were enriched with capabilities such as incorporating machine learning,
artificial intelligence, and smart decompilers.23

22
https://swagger.io/solutions/api-documentation/
23
https://github.com/JetBrains/intellij-community/tree/master/plugins/
java-decompiler

8
Chapter 1 Developer Tools and Language Services

If we consider smart suggestions in editors, tools such as Tabnine24 allows the user
to use auto-completion computed based on artificial intelligence. Tabnine computes
the auto-completions for more than one language such as Java, Go, CSS, Ruby, Python,
and many more. Users can install the Tabnine plugin for VS Code,25 Intellij,26 and even
for Vim.27 If we consider the navigation features such as go-to definitions and references,
they have advanced not only to navigate within a given project or a single source but
also to navigate among the archived sources such as jars and node modules. When the
Java programming language is considered, external dependencies can be added as jars.
From the usages of certain constructs in externally added jar bundles (classes, enums,
methods, etc.), the developer might wish to navigate to the actual source and explore the
implementation for more details. IDEs usually decompile the .class files with advanced
decompilers and navigate to the referenced content.
Apart from the aforementioned examples, language intelligence has addressed
various areas of the developer experience not just limiting to the textual information and
navigations. With the advancement of the IDEs’ and source code editors’ extensibility
support, the developers are provided with platform and ecosystem intelligence as well.
The integration of version controlling and service deployment tools such as Git, SVN,
Docker,28 and K8s29 are some examples of more advanced developer tools to enhance
language intelligence.

S
ummary
From the earliest programmable computers to date, the technologies and tools used for
programming computers have made a great leap. With the advancement of technologies,
computer programmers started to use and develop human-readable programming
languages and also more and more convenient tools to write their programs. While one

24
www.tabnine.com/
25
https://marketplace.visualstudio.com/items?itemName=TabNine.tabnine-vscode
26
https://plugins.jetbrains.com/plugin/12798-tabnine-ai-autocomplete-javascript-c-
python-ruby-rust-go-php--
27
https://github.com/codota/tabnine-vim
28
www.docker.com/get-started
29
https://kubernetes.io/

9
Chapter 1 Developer Tools and Language Services

of the earliest methods of composing computer programs was punched cards, today
programmers use more advanced and convenient tools such as IDEs and source code
editors.
In the last few decades, development tools have become more and more
intelligent, convenient, and powerful. Development tool vendors started inventing
and incorporating advanced technologies such as machine learning to enhance the
developer experience.
The Language Server Protocol was one such powerful tool which benefited language
providers as well as tooling providers to avoid repetitive, boilerplate implementation
when it comes to providing language intelligence for programming languages in a given
developer tool. The next chapter discusses the Language Server Protocol in detail.

10
CHAPTER 2

Understanding the
Language Server Protocol
In Chapter 1, we discussed the evolution of computer programming and various
development tools which were used to make the life of a developer easier. Among them,
we are going to focus more on editors and IDEs.
Today, developers have hundreds of IDEs, text editors, and source code editors
to choose from. When it comes to the editing experience and favorite tools, the users
are reluctant to switch between tools. In order to avoid this, tooling vendors started to
support more than one programming language, configuration language, etc.

Figure 2-1. Language provider and tooling vendor relationship

11
© Nadeeshaan Gunasinghe and Nipuna Marcus 2022
N. Gunasinghe and N. Marcus, Language Server Protocol and Implementation,
https://doi.org/10.1007/978-1-4842-7792-8_2
Chapter 2 Understanding the Language Server Protocol

Figure 2-1 shows how the relationship between language providers and tooling
vendors looks. Now, if you consider a tooling vendor implementing language features
such as diagnostics, auto-completions, and code navigations for a given programming
language, it takes a significant effort. Different tools have different APIs to support
language features, and these APIs have to consume the programming languages’ APIs to
consume the semantic and syntactic knowledge. This leads to using the same boilerplate
implementations again and again.
In order to avoid this repetitive work, Microsoft introduced the Language Server
Protocol to communicate between language clients and language smartness providers.
We call the language smartness providers the Language Servers. Clients implementing
the LSP can reuse the existing Language Servers to provide the language smartness
without implementing it from scratch.

Figure 2-2. Language Server Protocol

Figure 2-2 shows how a given editor implementing the Language Server Protocol can
support language smartness for multiple programming languages.

12
Chapter 2 Understanding the Language Server Protocol

In the coming sections of this chapter, we will be looking at the Language Server
Protocol1 in detail.

U
nderstanding JSON-RPC
The underlying base protocol of the Language Server Protocol is based on top of JSON-
RPC 2.0. The base protocol of the Language Server contains two parts, the header part
and the content part, which we will discuss in the next section.

JSON-RPC is a stateless, lightweight remote procedure call (RPC) protocol.

—JSON-RPC 2.0 Specification

JSON-RPC defines a set of JSON data structures and a set of rules over them. There
are two main data structures defined in the specification as follows:

1. Request object

A client sends an RPC call to a server with a request object.

2. Response object

The server responds to the client’s RPC call with a response object.

R
equest Object
Listing 2-1. Auto-completion Request Body Sent from the Client to the Language
Server
{
    "jsonrpc": "2.0",
    "method": "textDocument/completion",
    "params": {
        "textDocument": {
           "uri": "file:///Users/user/hello/test.bal"
        },

1
https://microsoft.github.io/language-server-protocol/

13
Chapter 2 Understanding the Language Server Protocol

        "position": {
            "line": 59,
            "character": 0
        },
        "context": {
            "triggerKind": 1
        }
    }
    ,
    "id": 10
}

Listing 2-1 is an example JSON-RPC request sent from a client (editor/IDE) to a

Language Server, requesting auto-completions in a given position. A request object
contains the following fields.

j sonrpc
This is the JSON-RPC protocol2 version used for the communication.

m
ethod
This is the name of the method to be invoked. The method name should be a string, and
method names starting with RPC are reserved for RPC-internal methods and extensions.

p arams
Represents parameters for the method invocation and this field is optional. Parameters
can be named parameters or positional parameters.

i d
The request identifier is established by the client and used to correlate between a given
request and a response. If this field is included, it MUST contain a String, a Number,
or NULL.

2
www.jsonrpc.org/

14
Chapter 2 Understanding the Language Server Protocol

N
otification
The request object has a variation without the id field which is defined as a notification,
and the server MUST NOT respond to a notification.

Listing 2-2. DidOpen Notification Sent from the Client to the Language Server

{
    "jsonrpc": "2.0",
    "method": "textDocument/didOpen",
    "params": {
        "textDocument": {
            "uri": "file:///Users/user/hello/test.bal",
            "languageId": "ballerina",
            "version": 1,
       }
    }
}

Listing 2-2 is an example of a notification, which represents a notification sent from a

client to a Language Server to notify a document open even in the editor.

R
esponse Object
Listing 2-3. Hover Response Sent from the Language Server to the Client
{
    "jsonrpc": "2.0",
    "method": "textDocument/hover",
    "result": {
          "contents": {
             "kind": "markdown",
             "value": "Get a string result.\n  \n  \n---  \n  \n###
Returns  \nstringReturned string value"
         }
    },
    "id": 140
}
15
Chapter 2 Understanding the Language Server Protocol

The response object contains the following fields.

jsonrpc
This is the JSON-RPC protocol version used for the communication.

result
The result value is determined by the server as a response to a corresponding request
method. This field MUST be included in a success scenario and MUST NOT be included in
the error scenario.

error
While the result field is included in the success scenario, the error field is included in the
erroneous scenario. In a response object, either the result or error fields MUST include
and MUST NOT include both fields in the same response.

id
This is the identifier value of the response, and this should be the same as the id of the
correlating request object.

Error Object
Listing 2-4. Method Not Found Error

{
    "jsonrpc": "2.0",
    "error": {
           "code": -32601,
           "message": "Method not found",
           data: {}
    },
    "id": "1"
}

16
Chapter 2 Understanding the Language Server Protocol

Listing 2-4 is an example error response sent for a request with a method that is not
supported by the client or the server. An error object contains the following fields.

code
This value MUST be an integer value and represents the error type that occurred. You can
read more on the error codes in the JSON-RPC Specification.3

message
This value SHOULD be a single sentence to represent the description of the error.

data
This optional field holds additional information about the error, and the value can be
either primitive or structured.

B
atch
Batches allow the clients to send multiple requests to the server. Except for the
notifications, the server MUST send back response objects to each of the request objects.
The order of the response objects can differ from the order of the requests, and the
requests and the corresponding responses should be correlated with the id.

Note The preceding information is extracted to provide the user a glimpse of the

data models and the JSON-RPC Specification. For more details, follow the official
specification.4

3
www.jsonrpc.org/specification#error_object
4
www.jsonrpc.org/specification

17
Chapter 2 Understanding the Language Server Protocol

Understanding the Base Protocol

The base protocol defines the header part and the content part. The header part consists
of header fields, and the content part adheres to the JSON-RPC format as described in
the earlier section. The following is an example message sent from a client to a Language
Server:

Content-Length: ...\r\n
\r\n
{
      "jsonrpc": "2.0",
      "id": 1,
      "method": ...,
      "params": {
                        ...
      }
}

As per the example, the header part and the content part are separated by “\r\n”. The
header part and the content part have the following characteristics.

Header Part
• The header field and the header value are separated by “: ”.

• A header field ends with a \r\n.

• The Language Server Protocol supports the Content-Length and the
Content-Type header fields.

Content Part
• This follows JSON-RPC 2.0, and the jsonrpc field is set to 2.0 always.

• UTF-8 is the default encoding.

18
Chapter 2 Understanding the Language Server Protocol

Communication Model
The Language Server Protocol’s communication is protocol agnostic. We will be
discussing in later chapters how to run a Language Server over standard I/O and
WebSocket. There are two main communication patterns defined in the LSP as request-
response and notifications. Requests and responses are correlated over the id which is
initiated by either the client or the server. Notifications can be initiated by either party
(client or server), and the receiving party should not respond to the notification.

Figure 2-3. A sample use case of how the server initialization and handshaking
are happening

The first request is sent by the client (IDE/editor) with InitializeParams, and the
server responds with InitializeResult. Any request before the initialize request will
be responded with an error response and notifications other than the exit notification.
When the client sends the initialize request, the server responds to the client with the
InitializeResult. In LSP, the initialize request can be considered as the handshake
phase of the communication.
19
Chapter 2 Understanding the Language Server Protocol

After the initialize request is sent and the server’s response is received, the client
sends the initialized notification to the server. In the depicted use case, the client
then sends the textDocument/didOpen notification to the server to notify a file open
activity in the client. Then the server publishes the diagnostics with textDocument/
publishDiagnostics notification to the server. For any of the notifications, neither party
would send a response, and a response is sent only for the requests. We will be looking at
these capabilities in detail from the next chapter onward.
Each message is assigned a method name adhering to the JSON-RPC protocol
specification, and except the general messages, other messages’ method names are
assigned a prefix. In the protocol, the following method prefixes can be identified.

General Messages
General messages’ method names do not have a namespace defined:

• initialize

• initialized

• shutdown

$/
Any method name starting with the $/ prefix depends on the protocol implementation of
the client or server. These methods are not guaranteed to be able to be implemented in
any client or server implementation:
• cancelRequest

• progress

window
Method names starting with the window/ prefix are used to show content on the client’s
user interface. For example, a showMessage notification can be used to show a message
on the editor’s user interface as follows. We will be discussing these methods and usages
in the coming chapters in detail:

20
Chapter 2 Understanding the Language Server Protocol

• showMessage

• showMessageRequest

• logMessage

telemetry
Telemetry events are sent from the server to the client to log the telemetry event:
• event

workspace
Method names starting with the workspace/ prefix infer any operation which can be
applied to the respective workspace. One such method is applyEdit which is a request
sent from the server to the client for applying changes to the text documents in the
workspace. Also, a didChangeConfiguration notification is sent from the client to the
server notifying the workspace configuration changes done. We will be discussing more
on this notification in the coming chapters on how we can use this notification in order
to dynamically register and unregister the capabilities and more:

• applyEdit

• symbols

• configuration

textDocument
Each of the notifications and request/response pairs starting with textDocument/
is associated with a specific text document. In order to identify the text document
associated with the method, a corresponding document URI is included in the content.
For example, a textDocument/didOpen request’s parameters contain a textDocument.
uri (as a JSON path from the content body) field. If the particular method is associated
with positional information as well – such as textDocument/definition – the position
details are also included in the content:

• didOpen

• didClose
21
Chapter 2 Understanding the Language Server Protocol

• definition

• reference

Note The order of the requests and the responses can be different depending on
the client and the server implementations. As specified in the protocol, it does not
enforce an order for requests, responses, and notifications. As a general rule of thumb,
the protocol specifies to consider the behaviors of the operations in the sequence, and
based on that, the order can be defined/handled in the implementation.

As an example, textDocument/hover and textDocument/definition can be

considered as a mutually exclusive request pair. Therefore, the server can change the
order of the responses for the aforementioned requests which are received in sequence.
When textDocument/definition and textDocument/format requests are considered,
it is not a good practice to change the order of the response. This is because the response
for textDocument/format refactors the source code and leads to a change of position of
the source code’s content, which can affect the response for textDocument/definition.

Note According to the current protocol version, the lifetime of the server is

controlled by the client. The client is the party to initiate the server process and kill
the process.

In the coming chapters of this book, we will be looking at the Language Server
Protocol in detail.

Summary
This chapter has provided a summary of the Language Server Protocol, what it is, and
how it operates. You’ve learned about the JSON-RPC standard upon which the protocol
operates, with JSON being the underlying format for requests and responses. You’ve seen
examples of the base protocol, including headers and content. And finally, you’ve been
introduced to the protocol-agnostic communication model. In the next chapter, you’ll
begin to learn how a Language Server is actually implemented.

22
CHAPTER 3

Implementing a Language
Server
In Chapter 2, we discussed the Language Server Protocol and how it works. In this
chapter, let’s look at how to implement a Language Server and what tools we need to
implement it. When implementing a Language Server, it is not only the language features
we need to focus on, but also we should have an underlying protocol implementation.
As we discussed in Chapter 2, the Language Server Protocol is implemented on top of
the JSON-RPC protocol specification. Therefore, the server implementation has to be
done along with the JSON-RPC protocol implementation. We will have a look into these
in the coming sections of this chapter.
In this book, we are going to refer to the Ballerina1 programming language which is
the reference language we are going to provide the language smartness.
For the reference language, we choose Ballerina for a few reasons:

1. It is easy to understand, and all the common language features

discussed in the Language Server Protocol can be implemented
for Ballerina.

2. Using a new language as the reference will allow the users to get
convinced about the gravity of the protocol.

3. Rich compiler APIs of Ballerina make the implementation easy.

Also, our Language Server implementation will be done with Java, and the client
implementation will be done with Typescript. In this book, we assume that the
reader has an intermediate knowledge about programming and familiarity with any
programming language. Also, we chose a different set of programming languages for

1
https://ballerina.io/

23
© Nadeeshaan Gunasinghe and Nipuna Marcus 2022
N. Gunasinghe and N. Marcus, Language Server Protocol and Implementation,
https://doi.org/10.1007/978-1-4842-7792-8_3
Other documents randomly have
different content
And for pleasure, too. I am a judeecious, reflective man. Here we
are in an empty ship idling across the world when we could have
stuffed the yacht full of high-priced cargo at any damn freights we
chose to extort. Ching, my commercial conscience racks me like a
raging blister. A cabin load each of drugs or dyestuffs would have
made our fortunes in South America, yet here we are with half a
dozen cabins empty. The wickedness of it scares me. The Humming
Top will come to no good when owners fly like yon in the face of the
bountiful freights of a kindly Providence. If I may say so without
irreverence, we are sacrileegiously biffing the Providential eye."
Captain Ching laughed. He was willing to venture freight on private
account when granted an opportunity. But this was a private
yachting cruise and orders were orders. If Sir John chose to burn
money to please Madame Gilbert—for that is how the long sea trip
presented itself to his mind—well, he had plenty to burn, and
Madame was well worth pleasing. He, as skipper, was handsomely
paid for his job, and that was enough for him. So was Ewing very
well paid. But the lost opportunities of plundering South American
Dagoes which slid unregarded past the easy-going Devonian just
exasperated the Scot from Glasgow.
"Please explain," put in Madame. "How can we gratify the bountiful
Providence who is displeased with the Humming Top? I am always
careful, when I can, to range Providence on my side."
The Engineer explained. He pointed out that here was a yacht with
half her cabins empty and stowage spaces unoccupied beneath their
very feet. Here also was a world bereft of shipping and every scrap
of space afloat worth almost as much as habitable houses ashore. It
would do no one any harm, least of all Sir John Toppys, the Owner, if
by judicious private trading Ching and Ewing could accumulate a pile
of wealth. "Of course Sir John would get his share—and you too,
Madame," explained Ewing, anxiously.
"Please leave me out," cried Madame, greatly to the relief of Ewing,
to whom an Owner's idle share gave pain sufficient, "I stand in with
Sir John. Is there any real reason, Captain Ching, why Mr. Ewing
should not do what he proposes? Would Sir John object?" It had
occurred to Madame that the Humming Top as a trader would be
accepted in the South Seas without comment, whereas a private
yacht, cruising at large upon an unexplained purpose, might excite
curiosity the most unwelcome.
"Not at all, I think," said Ching. "My orders are to take you to the
Torres Straits and to place myself and the yacht unreservedly at your
disposal. Sir John was most positive. I have among the ship's papers
written instructions directing me to obey any orders from you which
are consistent with the laws of British shipping. Sir John has very
complete confidence in your judgment, Madame."
"The more reason why I should not strain my temporary authority,"
said Madame. "Still in this matter of private trading I do not hold
that Sir John could reasonably take objection. We do no injury to
him nor to the yacht, and you, his officers, will perhaps benefit. You
have my permission to go ahead."
"Madame Gilbert," said Ewing solemnly, "you are the maist sensible
wumman it has ever been my fortune to encounter. Not excepting
Mrs. Ewing. I may add," he went on with enthusiasm, "that if I were
not a man happily married to a gude Scots leddy I would throw my
hairt into your bonnie lap."
"This is very sudden," said Madame. "For all you know I may be
married myself."
"No matter," cried the Engineer. "If you, a foreign leddy, are so ripe
with sense now what would you become with a gude Scotsman
beside ye? You and I together would scrape the jewels off the airth.
Meantime, with your permission, we will get busy. I take it that the
yacht will call at Plymouth and maybe stay two three days whiles I
communicate with my friends in Glasgow."
"If you are going to load the Humming Top with valuable stores, Mr.
Ewing, you will need a lot of ready money."
Ewing grinned. "We Scots folk are cautious, vairy cautious. Especially
when we deal with one another."
"Perhaps you need the more caution then," suggested Madame,
smiling.
"Maybe aye, maybe no. We don't push in our fingers farther than we
can draw the hand back. But in these days it is scarcely possible to
make a mistake. If we load up with opium, cocaine, and other
immoral dopes for the Dagoes we can't go wrong. They will pay any
money, and my friends in Glasgow will do the needful on credit.
They will ask a percentage, I don't deny that, but there will be a
margin. Ching, my son, are you game for dope smuggling round
Valparaiso and Lima way?"
"We must have creditable stores for the manifest," said Ching, "but I
don't suppose the Dago Customs will peer closely at a private yacht.
And a few honest dollars will blind their eyes I reckon. The Law is
not obtrusive on the West Coast, Ewing. But go easy with
contraband. We mustn't get Madame here into trouble."
"Don't worry about me," said Madame cheerfully. "I already feel like
a buccaneer. A bit of smuggling will give zest to a voyage which
threatens to be tedious. So let us stop in Plymouth for so long as Mr.
Ewing requires for his nefarious operations."
"I never thought to see the day," declared Ewing, beaming upon her,
"when my gude wife in Paisley would seem to be a sore
encumbrance. And after Plymouth could we not touch at Bordeaux?
French wines are always good mairchandise on the West Coast, and
the profits thereof would seduce old Pussyfoot himself."
"I clearly see," said Madame, smiling, "that when the Humming Top
leaves Europe for her long trail to the Panama Canal she will be
laden to her utmost capacity. We shall burn a power of oil to knock
out even eleven knots then."
"It will be worth it," cried Ewing, smacking his lips. "Even with fuel
oil at one hundred and fifty shillings the ton, there will still be a
margin. If we are loaded rail under with profitable stores I won't
grudge a cask or two of Sir John Toppys' oil. We play fair, Madame.
The Owner gets his share, a full honest share."
"For rank buccaneers and smugglers," observed Madame
contemplatively, "we seem to be indifferently honest. Go ahead, my
good but disreputable friends. And if you should require any cash I
am in this thing with you up to my fair neck."
"Madame," declared Ewing gloomily, "you make the recollection of
my gude wife fair burdensome to me, fair burdensome. We should
ha' made a bonny pair of pirates, you and I."
CHAPTER IV
IN THE SOUTH SEAS

If I had not set myself down to write the story of Madame Gilbert in
relation to His Lordship the Cannibal I should entertain my readers
with full details of the Humming Top's illicit enterprises. Abetted by
Captain Ching and Madame Gilbert, the capable Scot, Ewing, let
himself go. "It should never be said of me," he remarked, "that I
encouraged the vices of the Dagoes by making them inexpensive.
They shall find their sins a most costly luxury. In the eyes of the
judeecious my operations convey a strictly moral lesson." To dopes
and drinks he added chemicals and dyes of high commercial
importance. "In brand they are Swiss, but in parentage suspiciously
German; the Dagoes will pay the more for them on that account."
The stowage capacity of the Humming Top filled him with
admiration.
"The design of this boat," pronounced Ewing, "is vairy creditable to
my friend Ar-r-chie Denny of Dumbarton. He was not at the time she
was constructed the Baronet that he grew into; just plain Ar-r-chie.
He is a vairy far-sighted man, is Ar-r-chie Denny. When he designed
that snug wee hold below the main deck, so modest, so unobtrusive,
so shrinking from observation, yet so bountiful in capacity, he must
have foreseen that his yacht would find its way into gude judeecious
Scots hands. He is a vairy releegious man, is Ar-r-chie Denny. I shall
chairge the idolatrous Papists a price for the dopes and dyes which
will gratify his Presbyterian conscience. The Scots, you will observe,
Madame, are a grand God-fearing people."
"I am a Papist," whispered Madame. "It was not my fault, and I am
not a very good one."
"The better for that; the better for that," said Ewing, encouragingly.
"You need only a gude Scots Presbyterian husband and you would
become a pairfect wumman."
Ching entered with zeal into the lawless projects of the Scots
Engineer. His ancestors—and mine—had played the merry three-
legged game a few hundred years earlier, and, like all of true Devon
stock, he was unchangeable in temper. He was a smuggler by
inheritance. Out of Plymouth to the Slave Coast with beads and
trumpery—the first leg. From the Coast to the West Indies with a
cargo of blackbirds—the second leg. From the West Indies to
Plymouth with rum and molasses—the third leg. That was the merry
three-legged game with hundreds per cent. profit at the end of each
leg. And in those righteous days no excess profits duty. We of Devon
played it, and the Pilgrim Fathers of Rhode Island played it—with
geographical modifications—and we remained citizens of the highest
repute. John Hawkins, who began it, became a Knight by the hand
of Queen Elizabeth, and Treasurer of the Royal Navy of England. We
have fallen upon soft times, but even now the Devon folk—and Scots
like friend Ewing—revert to ancestral types and practices. "A far-
sighted man is Ar-r-chie Denny," murmured Ewing again, as he
stuffed packages into the snug wee hold between the main deck and
the ballast tanks. "He would just love to be here to see how we
appreciate his cunning war-r-k."
Ewing speedily found that Plymouth was an unsympathetic base for
his illicit operations. In the old days Cawsand at the western
entrance of the Sound had been a famous smuggling centre, but its
glory had departed. Plymouth itself was hedged about with
unromantic restrictions. Ewing's Glasgow accomplices could pass
down dyestuffs and chemicals in gratifying quantity, but dopes, the
glowing fount of profits, declined to flow.
"The English," wailed Ewing, "give no encouragement to honest
Scottish enterprises. Their jealousy is just parochial. There was a
time when one could ship any damn thing out of Glasgow, but there
is too much of the Royal British fossilised old Navy about Plymouth.
Those Keyham blacksmiths did their wor-r-st to strip my turbines
with their monkey tricks when the Humming Top was requisitioned,
and the port authorities are every bit as feckless as the Navy, all
forms and Customs regulations. Give me immoral belle France and
worthy dishonest Spain."
He did better at Bordeaux, and best of all at Lisbon, to which easy-
going jumping-off place his Glasgow friends ordered Switzerland to
consign the soul-raising dopes which England had barred as
immoral. There are few scruples about Switzerland and fewer still
about Portugal.
"We Scots are proud of our national institutions," remarked Ewing,
when Lisbon unfolded to him its charms as an abetter of crime,
"until we come to experience their rotten foolishness. We are too
intolerant and logical; give me the broadminded and wholly
unscrupulous Dagoes for business partners. We lack sympathy with
human weakness, but the Dagoes coin dollars out of it all the time.
If I were a wee bit younger I would turn Dago myself."
When at last the Humming Top cast off at Lisbon and stretched
away at her leisurely eleven knots for Colon and the South Seas she
was stuffed with stores of "prodeegious richness," all insured.
"But go careful, Ching, if you love me," implored Ewing. "I have
covered the lot on board of us at Lloyd's, but a claim won't bear
looking into. If we do get wrecked this side of Valparaiso, it has got
to be a thorough casualty. A total loss. A sunk ship tells no tales."
"We are not going to be lost," promised the Skipper.
"Speak softly, man," whispered Ewing. "Speak soft. Rub wood. Ye
carry Cæsar and his fortunes. There is sair peril in boastfulness at
sea."
To Madame the flagrant abuse of Sir John Toppys' marine hospitality
was a rich jest, packed with many a subtle stimulus to laughter. One
remorseless Fate—in the person of the late Hon. William Toppys—
had given a coloured Head to an ultra-respectable and unimaginative
English Family. A second Fate—in the person of naughty Madame
Gilbert—had corrupted the virtue of the Family Yacht, and set her
rollicking across the seas as a flagrantly unchaste smuggler. The
private list of her "soul-raising" stores, designed to pander to the
degenerate tastes of South American Dagoes, almost staggered
Madame herself, and she turned for the solace of her seasoned
conscience to the blameless manifest craftily prepared by Captain
Ching for the edification of the Panama Canal Board.
"You are sure there will be no examination?" she asked the Skipper.
"Sure," he said confidently. "We are landing nothing in the Canal
Zone, and the Board doesn't care two pins what we carry through."
"If that is so," murmured Madame; "if we get through without
scandal, I will tell Sir John Toppys all about it. He is a white man,
Captain Ching, who trusted me. One owes something," added
Madame virtuously, "to a white man who really trusts one."
Confession after crime was to Madame—and I am afraid also to the
"grandly releegious" Ewing—greatly to be preferred to weak
repentance before hand.
"It is the golden rule of life," said Ewing, "not to repent too soon.
There is a time and season for all things."
That very up-to-date yacht the Humming Top carried a wireless plant
and a Marconi operator. Aerials hung between the slim masts, and
their range of contact with the outside world extended for five
hundred miles—by day. By night it was much wider. The operator, as
they hummed along, picked up the news of the day for Madame's
edification; it cannot be said that he was overworked.
I think Madame's state room—it really was worthy of that abused
epithet—must have been designed for the use of Sir John Toppys
and his departed lady, in the days when space at sea was a new
luxury. With its appurtenances—a dressing-room at one end and a
bathroom at the other—it was thirty feet long, and it contained, as
has been said, a spring bedstead hung hammock-wise. The bed
gave discreetly to the roll of the ship. In the dressing-room which
had a door of direct communication, was installed Madame's maid, a
French girl who detested the sea and did not conceal her hatred.
She became reconciled to the months of sea travel by the gratifying
circumstance that she and Madame were two lone women in a man-
infested ship. Marie could do with a large surplusage of Man.
The saloon on the upper deck was the Mess of Madame and the
chief officers; to the two junior deck officers and the two assistant
Engineers was assigned the Mess Room aft on the main deck out of
which their cabins opened, and to them, at their own request, was
added the society at meals of Marie.
"How many?" enquired Madame, when Ching diffidently
communicated the invitation. "Four of them? Marie could keep a
dozen busy. She will make four hop pretty briskly." In spite of bouts
of sea-sickness I fancy that Marie enjoyed her voyage.
Between Madame Gilbert and her companions grew up a close
friendship. She talked freely with them except upon the purpose of
her travels. That was maintained for the present as a Family Secret.
They, simple creatures, sometimes wondered why Sir John Toppys
should spend so much money upon Madame's pleasures and refrain
from sharing them with her. His absence was grateful in their sight—
for did they not between them monopolise a most gracious and
entertaining lady?—but they often wondered at his lack of
enterprise.
"Ching," said Ewing confidentially, "you are married as tightly as I
am, and both of us are faithful—in reason—to our wedded wives.
But if you had the chance of an unlawful holiday cruise with our
beautiful Madame Gilbert, would you not jump at it?"
"Ewing," said Ching, as confidentially, "I am a sinful man. I should."
"Sir John Toppys must be a meeracle," declared Ewing, after a long
pause.
"Perhaps it is Madame who is the miracle," observed the Skipper
shrewdly.
The ripe flavour of Ewing's Scottish character was not appreciated by
Madame Gilbert until a conversation took place off Valparaiso, for the
contraband cargo had all been disposed of—at cash prices—and
Ching and Ewing were counting up their gains in Madame's
presence. Half the profits were set aside for the Owner of the
Humming Top, and were safely locked up with the ship's gold in the
Captain's safe.
"It's an awful sum of money to pay over to the idle rich," wailed
Ewing.
The "Idle Rich," as Madame and Ching pointed out, had not only
provided the vessel for their illicit trading operations, but had also
paid handsome wages to the crew—including their noble selves.
Incidentally his idle wealth purchased the tons of oil fuel—at steadily
advancing prices—which they drew aboard at Colon and purposed to
take in at Auckland. The "Idle Rich" supplied the Capital and working
expenses; Ching, Madame, and Ewing the unscrupulous Labour.
Madame, it may be observed, received nothing: Ewing and Ching
drew fifty per cent. between them.
"Was not that fair?" enquired Madame.
"As a matter of metapheesical exactitude," replied Ewing cautiously,
"I would not deny that the Owner's half-profit is defensible. From the
point of view, mar-r-k my wor-r-ds, of the Idle Capeetalist. But the
Spirit of the Age, Madame, is not concairned solely with—with the
boodle. The news which flickers in over our most efficient wireless
apparatus indicates that the Wor-r-kers of the Wor-r-ld are all on the
Grab. I am a wor-r-ker, Ching is a wor-r-ker, you, Madame, are a
wor-r-ker. Sir John Toppys is not a wor-r-ker. I don't suppose that
the little man has ever sweated in his life-except maybe at the gowf.
To the wor-r-kers belong the profits. That means Ching and me."
"But I am also a wor-r-ker," put in Madame slyly.
Ewing shuffled uneasily. "I have said so, and I bide by what I have
said. But you have waived your rights, Madame. Ching will bear
witness."
Madame laughed. Then an idea struck her, and she gleefully cast it
in Ewing's voracious teeth.
"I have waived my rights. But your officers and men have not
waived theirs. They are wor-r-kers. They have navigated the ship
which has sailed the seas and carried the goods which Ewing and
Ching and Madame—and those friends of yours in Glasgow—have
bought and sold. By comparison with the junior officers and the
humble men, you and I are little better than idle rich ourselves. We
just give the orders; they do the hard uninteresting wor-r-k. We loll
smoking here while they sweat. Surely they should have their share
of the boodle."
Horror competed with exasperation on the harsh red face of the
Chief Engineer. With difficulty he awaited the end of her speech and
then burst out:
"Is it possible, Madame Gilbert, that you are a Socialist? I could not
have believed it of you if I had not hair-r-d your terrible wur-r-ds
with my own ears."
"I am more than a Socialist," said Madame proudly. "I am a
Bolshevist where the humble poor are concerned."
Ewing shuddered. "I could not have believed it. It is just peetiful
trash that you speak. And you in other respects a maist sensible
wumman. What is ceevilisation?" Ewing flung out this large inquiry,
and an answer not being offered, proceeded to supply one himself.
"Ceevilisation is brains, Madame. Capital is not brains; it is gilded
idleness levying toll on the honest wor-r-ker. Toilsome sweat is not
brains; it just stupidly does what it is told by superior intelligences.
Sir John Toppys is not ceevilisation. The men who obey our or-r-ders
above deck and in the engine-room are not ceevilisation. WE are
ceevilisation. Ching and I—and you, Madame, who have waived your
claim to a share. And quite right, too. In strict economic justice, I,
Alexander Ewing, should draw a lairger dividend from the boodle
than Rober-r-t Ching. And for why? Because I have the mair brains.
The oreeginal idea of this smuggling plant was mine. But I say
nothing about that," he added generously. "Share and share alike.
But if," he went on with vicious emphasis, "any of my engine-room
hands, or my Engineers, peer their noses into my private enterprises
I will sor-r-t their fat car-r-cases with a coal shovel. Ceevilisation is
brains, Madame. Don't for peety's sake tell you fearsome Socialism
to me any more. I just canna bear it."
The plunder was all in fat United States dollars, a noble currency
which towers like a mountain peak amidst the wreckage of European
depreciated paper. Ewing saw to that. He dribbled out his highly
demanded stores in quantities that rather added to than diminished
the exuberant buoyancy of the market. He was a Scotsman who had
made a Corner, next perhaps to a Scotsman on the Make the most
noble Wor-r-k of God. Dagoes of varied hues, and of more than
doubtful parentage, came and went; they were closeted with Ewing
in the saloon, and departed stripped. They got their dyes and their
chemicals and their naughty dopes, but what a hair-raising price
they were compelled to pay!
"I am no profiteer," declared Ewing. "Just a plain, honest Scottish
mairchant. I chairge no mair than the mar-r-ket will bear. And I have
a suspeecion that there will be no excess profits duty paid on this
deal. We are private persons engaged in honourable professions, not
traders or registered partners. Besides we are out of the jurisdiction
of the wucked English income tax. We are patriots, too, employed
upon the noble wor-r-k of reconstructing the trade of the British
Empire."
When one combines lofty patriotism with some five hundred per
cent. profit, the result cannot fail to be profoundly gratifying.
CHAPTER V
WILLATOPY: PILOT

They drew away from the South American Coast and headed for
New Zealand and the Coral Sea beyond. And as Robert Ching pored
over the chart of the Coral Sea it was borne in upon him that the
navigation of those many spiked waters would, in the absence of a
pilot, be as big a job as he wanted. The Humming Top drew no more
than ten and a half feet of water, and was specially guarded under
her keel by six inches of solid teak—Ching had demanded the false,
protective keel before he would consent to take the yacht to the
Torres Straits—but she was big enough to tear herself to pieces on
those frightful coral teeth if permitted to swerve only by a little from
the tortuous channels.
"I shall have to do without a pilot most of the time," said he. "There
is a large regular trade and not enough pilots to supply wandering
yachts. We must go back to the methods of Drake and Cook—keep
the lead going by day and lie up at night. A sailor can smell his way
along anywhere if he is not pressed for time."
Madame promised him all the time that there was—she was enjoying
herself and in no hurry to get at grips with the problem of the
Twenty-Eighth Baron of Topsham. Every week which passed at sea
made the purpose of her voyage seem more bizarre and incredible.
Yet she was constantly reminded of its reality. Though they knew it
not, here were Ching and Ewing, together with some two dozen
officers and men, at a cost which ran into hundreds of pounds a
week, steaming to the ends of the earth solely for that bizarre and
incredible purpose. Madame had made her own position luminously
clear. She was going with no plan and under no promise. She was
not going to smother Willatopy or tip him into the sea—which would
have been of little use since he swam like a dolphin. She was not
going to poison his food or even to kidnap him. She was simply
going to see what this half-caste Baron looked like and to order her
movements in accordance with her impressions. She talked with
Ching and Ewing upon every subject in earth or heaven except this
one. The Family Secret must remain secret until the day arrived
when secrecy should avail nothing. When that day would dawn
Madame had no idea. To anyone except Sir John Toppys—and
curiously enough Roger Gatepath—the whole expedition would have
seemed a ridiculous waste of money. But both of them were at their
wits' end, and both of them had a childlike faith in Madame Gilbert's
lively intelligence and resource. Something striking would result from
the voyage, of that they felt convinced; though what it would be
they had no conception. Neither had Madame. Yet she went. The
Family Misfortune intrigued her, and she wanted to see it at close
quarters, and to make it crawl to her feet and eat out of her hand.
When at last they warped up at Auckland Ewing himself sounded the
fuel tanks in the Humming Top's double bottom. He had sworn by
his holy gods—the twin high-speed Parson-cum-Denny geared
turbines—that the yacht would run from Panama to Auckland, via
Lima and Valparaiso, on the 230 tons of fuel oil which she bore away
from the Canal Zone. She had done it, and the Chief was curious to
see by what small margin his judgment as Engineer had been saved
from derision. The margin was just nine tons, say 270 miles of
steaming at eleven knots.
"Thirty miles to the ton or thereby," murmured he, "and very good
wor-r-k too. Yon's a useful figure to bear in one's heid."
At Auckland he filled up chock a block, side bunkers and ballast
tanks, and felt confident that he could go up to Thursday Island,
toddle about at low speed in the Straits so long as it pleased
Madame to toddle, and then make his way back to the Auckland
tanks while, so to speak, some shots remained unburnt in his locker.
But the price of oil at the Antipodes struck horror to his thrifty heart.
Suppose—it was an awful suppose—Sir John Toppys, obdurate to the
wheedlings of Madame, who had promised to do her utmost to make
the owner waive his share, should insist on debiting the cost of the
voyage to that "owner's share" of the illicit profits. It was a dreadful
supposition. Ewing thrust it from his consciousness; even the Idle
Rich could not be so utterly soulless.
At Auckland in addition to the stores of oil fuel they shipped trading
goods for the Islands, and stowed them carefully away in the empty
cabins and in the snug wee hold which had already served the
adventurers so well. These saleable commodities were designed to
give to the wandering yacht a commercial status, and might possibly,
almost certainly, add some few dollars of profit to their bursting
treasury.
"One can never make too much profit," explained Ewing, "especially
when one doesn't pay any excess taxes to an extortionate English
Government. Cash, in American dollars, tells no tales."
Ewing had already decided that the Humming Top should look in at
an American port on the way home, and that the boodle should be
deposited out of harm's way under the protection of the Stars and
Stripes. A dread lest the tax gatherers of England might yet grab
some of it possessed him. In his management of the Auckland stores
his genius for finance rose to lofty heights.
"We will invest the alleged share of Sir John Toppys in this Island
trade," declared he. "If we make a loss—and it is not a business
which I vairy clearly comprehend—then the loss will fall upon the
Owner of the yacht. Which is just. Idle and rich owners must take
some risk; that is what they are for. If we realise a profit—and my
friends here say that the Islands are stripped and will buy anything
ravenously—if we realise a profit, of course it belongs to us who
have airned it. To me and Ching," he added hastily, lest Madame
should intrude with a claim. "Sir John's share will be put back,
untouched; we are honest men."
When Madame hinted that righteous dealing had not quite been
given a full rein, Ewing protested sorrowfully that as an operation of
business what he proposed was spotless, white as driven snow on
the bonny hills of Scotland.
"Sir John is a capeetalist," said he. "He would not wish his funds to
lie idle in yon safe. He would wish that they should be employed in
the reconstruction of the British Empire. That's what we are going to
do with them. Would you leave his money fruitless just because we
are twelve thousand miles away and cannot ask his permission to
employ it? Would you be baffled by a formality like yon? Capeetalists
always love to tur-r-n their money over. We will tur-r-n Sir John's
over for him. We will make it skip. It's going to belong to us anyway
—you have promised to see to that, Madame—although for the
moment we are holding it for him. Do you not reflect also, Madame,
that a whole five per cent. of Sir John's share is going to the officers
and crew and I have got to make good the grievous loss which your
Socialism has brought upon me. I have to carry that feckless Ching
on my back too. He would give the lot away like a pound of mouldy
tea if I were not at his elbow to keep him heedful of the future. I am
not what you could exactly call a man of business, but I have
grasped the inherent principles of the job."
"You grasp the principles—and most other things," said Madame,
smiling. Her joy in Ewing never failed, and between the pair had
grown up a very close affection. She liked the simple, kindly,
unselfish Ching, but as a study in humanity he could not compete in
interest with the great Alexander.
Ching made no mystery of the sea craft in which he was a master.
He took Madame and Ewing wholly into his confidence, and earned
their full confidence in return. The yacht was about to sail in waters
where destruction awaited eagerly any slip by a careless navigator,
and Ching was not taking any risks which could be avoided.
"I am not going to see more of the coral reefs than I'm obliged,"
said he, during the first dinner out of Auckland. "We shall get our
bellyful of them in the Straits, especially if Madame here has a fancy
for uncharted channels. I am taking the Humming Top by the outer
passage, as far east of the Great Barrier as I can get, and then come
down to Thursday Island by the Bligh Entrance. You've heard of
Bounty Bligh, Madame; he was a masterful man, and always stirred
up a mutiny wherever he commanded. There is a well-known inner
passage between the Barrier and the Queensland Coast; it is
sheltered and lighted like the Strand, but as it isn't much wider I'm
not taking any of it. I couldn't look at the passage without a pilot,
and there might not be one to the Humming Top. She's a vagrant
yacht, not a real ship."
"She is an Island trader," corrected Ewing with dignity.
"Humph," replied Ching. "A ton or two of frippery doesn't turn a
yacht into a ship. We are a rich man's toy, and don't count for much
on the high seas. Our burgee and Blue Ensign look consequential at
Auckland, but an ancient Island schooner would make more stir in
the Straits."
"Wait till they see our engine-room," cried Ewing. "There's nothing
like it outside the King's Navy."
"Humph," replied Ching again. "They wouldn't look at our engine-
room if there was a dirty craft alongside which would load up their
copra and beche de mer. Trade must run both ways to be taken
seriously. I take it that we are not going to carry copra to the English
soap boilers or smoked sea slugs for the Chinese soup market. And
if we don't do both the Island trade has no use for us and no
interest in us."
"You make us feel humble," said Madame, smiling. "I had become
proud of the Humming Top."
"She's a fine craft, but a yacht isn't a real ship, Madame."
"She was a real enough ship when you and I ran her in at seventeen
knots under the guns at Zeebrugge to pick up the Navy boys in the
watter," shouted Ewing.
"That was another Service," returned Ching stolidly. "She was a ship
then. Now she's a yacht. I'm proud to command her now, as I was
then; but I want to make you see that as a yacht she has no status
on the seas. If pilots are scarce we shall have no call on one. We've
got to run our own risks by ourselves and to make them as small as
we know how. Is that clear?"
"As crystal," said Madame. "Also humiliating. And I thought I was
rather a swell cruising about the world in a yacht which was
practically my own."
"You always would be a swell anywhere," said Ching politely. "But on
the high seas the mistress of a yacht doesn't count for a row of
beans."
"Don't heed him, Madame," cried Ewing. "He's only a demobbed
Commander R.N.R. Your friend Alexander Ewing will stick up for you.
I was an Engineer Lieutenant, and the engine-room ranks much
higher than the bridge nowadays, though it may not sport so many
rows of gold lace. It is my deliberate opeenion, arrived at by careful
consideration of all the circumstances, and after giving full weight to
the observations of my commanding officer, that we shall get on
quite nicely without a pilot, thank you. I am not exactly what you
could call an experienced navigator, but give me a well-found vessel
of light draught, with six inches of teak fender to her hinder end, a
diligent crew heaving the lead at discreet intervals, all the eyes on
the bridge looking sprightly for promiscuous breakers, and I would
con the Humming Top myself. The mair especially if I could be in
two places at once and be in chairge of my bonny engines at the
same time as I strolled majestically about the bridge. There is no
real deeficulty about navigation, Madame. Yon's not like to the
management of high-speed geared turbines. Yon's child's wor-r-k
with Admiralty charts spread about ye. But since I cannot be, like
the fabulous bir-r-d, in the two places at once, I will leave the bridge
to our deefident friend Ching. Go ahead, dead slow, among the
prickly reefs, and if you should just butt on the ground give the wor-
r-d to me by the engine-room telegraph and I will whip her off on
the revairse. That is the grand advantage of geared turbines,
Madame. One has the full power on the revairse. What did you go
for to put teak to the bottom of us, Ching, if you didna expect to find
a use for it?"
"It was a precaution," said the Skipper, "like a fender. One doesn't
bang the sides of a ship against a stone wharf because one has
fenders. I have seen a fender break through the plates before now
when used without judgment."
"You are a careful man, and we trust you, Ching," said Ewing
encouragingly. "Go ahead, pilot or no pilot. And if you should get
into trouble deeper than your brains can penetrate, there is always
the voice pipe handy. Take counsel of Alexander Ewing. He will stand
by ye."
"I will," returned the Skipper, "I will ask you how to run my ship
when you ask me how to manage your engine-room."
"Alexander," said Madame severely, when the Captain had left the
saloon for his own duties, "if Captain Ching were not a sweet-
blooded angel he would kick you hard. I should. Don't you see, you
thick-headed Scotch mechanic, that the Captain is worried, and
when a sailor like that is worried, the danger must be considerable. I
am ashamed of you, Alexander."
"It was just pairsiflage, Madame," said Ewing. "A wee bit of vairy
humorous pairsiflage. I know my place. Though I have mair gude
Scots brains in my finger than all the soft West Country porridge
stuff in Ching's head, I would never interfere with the bridge. A Chief
Engineer is a man of science, not a rule of thumb navigator."
"You had better not," quoth Madame. "Ching is slow and quiet. He
has no small talk, and, it must be confessed, is sometimes a bit
heavy on hand. He is not a lively companion like our Alexander. But
in a misspent life I have learned something of men, and I bank on
Ching. Mar-r-k my wor-r-ds, Sandy. He will bring us through the
reefs without scraping our false keel, and if you chaff him at a
moment when he is really anxious he will chuck you into the Ditch.
The Scotch are a great people, but they are not conspicuous for
tact."
It was well into May when, far up in the Gulf of Papua, Ching swung
the Humming Top to the westward, and began the hazardous
unaided penetration of the coral barriers which lay between him and
Thursday Island. The weather was perfect and could be depended
upon. It was the season of the regular south-east trade, the sunny
rainless season of the Torres winter. The wind would gather strength
every morning to a half gale at noon and then as evenly decline to a
calm after sunset. The tides ran very strongly, between three and
four knots, and gained in speed as the Straits narrowed, but to
judge their tidal drift, and the variable leeway due to the rise and fall
of the trade wind, was child's play to a seaman of Ching's quality.
Upon his chart were marked all the islands—many of them loftily
volcanic, others low coral atolls—and the sandbanks, known locally
as cays. He could work by taking bearings of the more conspicuous
island features, and by calculating his horizontal danger angles with
a generous margin. He assumed that every island had an inner
fringing reef and an outer barrier—though many of them had no
barrier—and that every turf-swept cay shelved slowly into the
depths. Time was not his master, and Ching was a cautious man.
When one evening, just after sunset, he raised the beacon on the
Bramble Cay, and found the position of the yacht very near to his
dead reckoning, he patted himself on the back and went to dinner
with a mind temporarily at ease. He dropped his anchor off the Black
Rocks at the exact point for which he had aimed—the Bligh Entrance
to the North-East Channel.
"Now the fun is about to begin," said he, smiling. Madame plied him
with broad flattery, and the Chief did his rather clumsy best to
support her. Now that the yacht was actually in the Straits, Ewing
had enough of good sense to attend to his own job, and to leave
Ching unharried to attend to his. Both Madame and Ewing were well
pleased to see the Captain smile.
Navigation on the following day would have been less hair-raising if
the chart had been half as wise as it pretended. But since most of its
features were based upon surveys of some half a century earlier, and
the coral polyp is an industrious creature, there was a wide margin
of conjecture left to the hardy sailor. The channels were deep
enough—Ching sometimes had fourteen fathoms and usually not
less than ten under his forefoot—but there were so many of them,
and they were so liberally cut into by what in trench warfare were
called traverses, that running a vessel through them was very like
threading an imperfectly remembered maze. Still the Skipper's eye
for water held true, he could generally tell by the look of the surface
if the reefs were closing in upon him, and the lead which was freely
kept going warned him off the sandbanks. He ran dead slow all
through the day, except when the tide setting against him called for
half speed. More than once he was obliged to stop and back out of a
cul de sac, but, as I have said, there was usually plenty of water
under foot, and a timely warning by eye or lead when obstructions
were reaching up towards the broken surface. All through the day
the Humming Top never touched once, and Ching began to feel that
he needed but a licence to rate himself a pilot of the Straits. But his
self-satisfaction was not destined to last very long.
It was about five o'clock, and for an hour past the Skipper had
noticed a fully decked yawl, sailed apparently single-handed,
following on his own course about a mile to leeward. With the tide
under her, and sailing on a beam wind, this thirty-foot yawl was
moving rather faster than the big yacht which she was gradually
overhauling. The yawl pulled in more and more to the south-west,
and passing astern of the Humming Top, reached out towards a
group of islands which Ching judged to be away from his own
channel. He himself bore off almost due west, and the gap between
the steam yacht and the yawl opened out rapidly. That was at about
five o'clock. Ching was therefore surprised half an hour later to see
the yawl come flying out of space with the wind behind her, and
steering direct for his own port bow with apparently a complete
disregard for the intricacies of the coral channels. He put up his
glass. The yawl was, as he had judged, sailed single-handed. Her
skipper, a small white figure with a bare black head, was sitting by
the tiller, and, as Ching looked, he seemed to be waving one hand.
There could be no doubt that the yawl was making for the yacht, so,
with sailor courtesy, Ching ran off his engines and waited for the
little craft to arrive.
She came with a rush and swirl which showed at least, high courage
in her solitary navigator. She passed the bow of the Humming Top at
about a hundred yards distance, swung under the lee of the yacht,
and skilfully used the flow of the tide as a brake upon her progress.
The white figure sprang up, let the yawl swing with flapping sails
into the wind, and then in thirty active seconds had lowered and
roughly stowed mainsail, jib and foresail. He left the spanker
standing set on the small mizzen aft. The whole manœuvre was so
accurately timed that the yacht had lost her way when she arrived
close beside the Humming Top's counter. In a moment more the
visitor had caught a line which was deftly thrown to him from the
yacht, reeved it through a ringbolt by his bowsprit, hauled his little
vessel half round, and sprang, active as a monkey, up the seven feet
of freeboard to the Humming Top's rail. His deserted yawl trailed
away at the end of the line, and her late skipper and crew, now
aboard the Humming Top, strolled forrard grinning capaciously. It
could now be seen that though clad in the white Palm Beach
trousers, and fine cotton shirt of an Englishman, he was a dark-
skinned, frizzy-haired Melanesian. His feet were bare and his head
was bare; the shirt and trousers seemed to comprise his entire
wardrobe.
He moved forrard looking curiously and eagerly at the yacht's
equipment. He mounted the steps of the shade deck on which were
stowed four lifeboats, a small dinghy, and a twenty-foot motor
launch. His eye ran closely over all of them; the motor boat seemed
specially to please him. He passed the yellow funnel, and peered
into the smoke-room, a pleasant structure in which Madame Gilbert
spent much of her time on deck. She was within at the moment
knitting her ninth jumper—she caught a glimpse of a dark grinning
face, and started slightly at the contrast between the brown of the
face and the bright blue eyes which looked eagerly out of it. It was
the face of a boy of some twenty years. Madame saw him for a brief
instant, and wondering who he was, and how he had reached the
yacht—she had not witnessed his masterly boarding operation—
came out on the boat deck to see more. An unexpected incident is
very welcome indeed on a long voyage unbroken except by
smuggling operations and the knitting of jumpers. The boy reached
the chart-room and wheel-house above which was built the bridge,
with its engine and steering telegraphs. Ching from the bridge
looked down upon the boy, and the boy looked up at Ching. The
visitor waved a hand at the Captain.
"Cheerio, Skipper," cried he. "You are a bit off your course, aren't
you?" His voice was not unpleasing and his English was surprisingly
good for a coffee-coloured native—dark coffee, too.
"That depends on what the course is," replied Ching shortly. He was
frowning, and his genial eye had gone cold.
What I have described did not occupy more than a very few
minutes, during which time the yacht, with her engines stopped, was
idly drifting under the influence of wind and tide.
"At present," said the boy, showing his fine white teeth as he
grinned broadly, "you are bound for the Warrior Reefs. That was why
I boarded you."
Ching spoke briefly to a sailor who was with him on the bridge, and
then dropped down to the chart-room beneath. The boy mounted
the bridge ladder, and took a comprehensive look round. What he
saw did not please him. His blue eyes hardened—they were bright
steely blue, very unusual eyes even in an English face, and
incredible in a native of the Torres Straits—and going straight to one
of the engine-room telegraphs pulled the lever over to half speed
astern. The bell clanged.
As a wounded tiger bursts open-mouthed and raging from its
ravished retreat in the jungle so Ching furiously burst from the chart-
room at the sound of that bell. And for my part I would sooner face
a wounded tiger in the jungle than a mild-mannered Devonshire ship
captain upon whose engine-room telegraph I had set my lawless
hand. The Skipper sprang on the bridge pushed the boy away so
roughly that he sprawled over the weather cloths, snapped the
telegraph back to STOP, and roared:
"Chuck this nig—young feller into his boat and cut him adrift." It
says much, very much, for the inherent kindliness of our Robert
Ching that even under stress of an unparalleled trespass upon his
prerogatives as commander, he bit back the offensive word "nigger."
The sailor sprang at the boy, who evaded the rush with lithe ease.
He was quite calm, and still grinned cheerfully.
"Wait," cried he, in a tone so gleefully significant that the sailor
stopped, and even Ching looked up curiously. "Wait," cried the boy,
holding up his hand. They waited until one might count perhaps ten,
and then that for which they waited befell:
G-RRR-H, G-RRR-H, G-RRR-H!
The Humming Top took the hidden reef with a slow grinding crash
which made her shiver, and under pressure of wind and tide she bit
deeper and deeper into the coral. It was well for her at that moment
that between her steel plates and the reef there interposed the
faithful baulks of previsionary teak.
The boy, with a heedless courage which to me seems almost sublime
—after all a skipper is a skipper and a very great man on his own
bridge—the boy pushed past the Captain of the yacht, laid his brown
sacrilegious hand once more on the engine-room telegraph, and
banged the lever over to FULL SPEED ASTERN.
"Go," he said sharply to the amazed sailorman. "Jump into my yawl,
and fend her off as we go astern."
I am afraid that when that crash came the Chief Engineer laughed.
He had seen nothing of the incidents on deck, but the sudden
grounding of the yacht, after the strange vacillations of the
telegraph, suggested that Ching had blundered badly. And Ewing, as
a platonic rival with Ching for the favours of Madame Gilbert, was
not disposed to cry over the Skipper's troubles. He gave full speed
astern with a will and under the hefty pull of the twin screws the
yacht was dragged off within a few seconds. The tide happily was
flowing.
"Keep her so," ordered the boy, indicating the correct course with his
hand, and the Skipper, to his own surprise, kept her so. There was
an intimate local knowledge and a masterful confidence about this
intrusive Melanesian which made him irresistible.
From that moment, extraordinary as it may seem to the reader, that
strange boy took charge. He set the backward course, and kept the
Humming Top at full speed astern for more than three miles. Ching
had overshot a hidden turning in the channel; he had run into a
narrow byway in which there was no space for so long a vessel to
turn round. She was 230 feet over all. The new pilot quite evidently
needed no chart, and possibly would not have understood one had it
been spread before him. Every reef and bank was as familiar to him
from constant sailing by them as are the streets of one's native
town. He conned the Humming Top by movements of his hand, for
though he understood the uses of an engine-room telegraph, that
other telegraph which controlled the wheel below was apparently
strange to him. He gave his orders by signs and the rightful skipper
humbly obeyed. It was a triumph of intensive local experience over
professional training.
When he had backed the yacht a sufficient distance to satisfy his
own judgment this boy sent her forward once more—not at poor
Ching's cautious dead slow or half speed, but at a ramping eleven
knots—following the windings of the deep waterways with
consummate assurance. Now and then, when it seemed to the eye
of Ching that he was running straight upon surf-broken dangers, a
sailor would be ordered forward with the lead, but the result was
always the same. The depth was never less than ten fathoms, and
the broken water was an innocuous tide rip.
This went on for more than an hour, the evening drew on, and
Ching, at last convinced that he was in the hands of a master of the
Coral Sea, spoke. Hitherto he had obeyed the signs of the boy,
obeyed though savagely reluctant, yet had said nothing. Now he
spoke.
"Are you a pilot, boy?"
"Oh, no. I am no pilot. I am very rich and do not work. I was sailing
down to Thursday Island in my yawl—to see my banker and collect
my money. I have much money. When I saw you running this nice
ship on the Warrior Reefs I sailed across to show you the proper
way. No pearl raking pilot can teach me anything. They are no good,
no good at all."
"You seem to know the channels," assented Ching.
"All of them," said the boy. "Not these only for a big big ship, but the
little ones too. I do not sail in and out as I am taking you now. I cut
across wherever I please. There is always water to be found if one
knows where to look for it."
"It is getting dark," said Ching, "and there is a short twilight in these
latitudes. Can you see or shall we anchor now?"
"I can see. I can steer you all through the night if you please. But if
you and the white lady, the beautiful white lady with the hair so red,
would wish to anchor, I will take you to a safe place." His hand
waved here and there; the growing darkness made no difference to
him, and presently the Humming Top was riding quietly at her
anchor in the lagoon of a low coral atoll. The boy had conned her
through the barrier reef and laid her up in the smooth water within.
Ching gasped as the yacht slipped in through a narrow gap in the
reef little wider than her own 30 feet of beam. It was like pushing a
Rolls-Royce in between two threatening motor lorries.
"Boy," said Ching slowly, when the anchor had splashed into the
warm quiet sea. "I meant to throw you overboard and you jolly well
deserved it for monkeying with my telegraph. But I will say that you
are a daisy of a pilot."
As they came down from the bridge they met Madame by the
smoke-room.
"Who is that?" she enquired. "A native pilot?"
"No," replied the boy, before Ching could speak. "I am no pilot. I am
very rich and do no work. I am going to Thursday Island to see my
banker and get my money. I am Willatopy."
CHAPTER VI
A NIGHT IN THE STRAITS

They were gathered in the smoke-room which was planted upon the
boat deck abaft the chart-house. It was the snuggery held in
common by Madame and Ching and Ewing; to them was now added
another—Willatopy, Pilot. Madame, when she heard his name so
unexpectedly had switched up the lights behind her and invited him
to enter. She wanted to see him clearly, and to collect her thoughts.
All through the long voyage she had pictured her meeting with a
naked Cannibal in the appropriate setting of a tropical coral island.
Yet here and now had come to her out of the seas a young man,
passably English in dress except for his bare feet, passably English in
speech, and a good deal superior to the English in his masterly
knowledge of the variegated depths of his native seas. The blue
eyes of this young man who called himself Willatopy had astonished
her when first she came under their quick steely flash; now when
they were bent upon her, quite plainly in admiration, she sensibly
shrank before their bright intelligence. They were the Toppys eyes;
she had admired them when set in Sir John's pale face; out of the
dark, almost black countenance of young Willatopy they shone like
beacons. They were beacons, the burning evidences of his Toppys
blood.
It was their first night in the Straits—what Stevenson, pumped dry of
tropical epithets, so often called "a wonderful night of stars." Yet
Madame Gilbert had no eyes and no mind for the wonder of it. She
could think of nothing but the Cannibal who for months had seemed
to be so very remote and who was now so very near. Indeed exactly
opposite to her, seated cross-legged like an Englishman upon a sofa
bunk. His lips and nostrils were rather thick and broad, and his hair
distinctly negroid—one should, I suppose, say Australoid—he was of
the colour of strong coffee, yet he was not in the least like a
Cannibal.
"Gatepath must be even a bigger fool than I thought," muttered
Madame angrily to herself. Which was unjust. She had not, like
Gatepath, been chased down to a boat by a naked furious Willatopy
urged on to speed by the prod of a fish spear. But at that moment
Madame was unwilling to be just, especially to Roger Gatepath.
"What makes your hair so red?" asked Willatopy suddenly.
"It grows that way," murmured Madame feebly.
"I have never seen hair red like that," observed Willatopy. "At
Thursday Island the white women's hair is black or muddy. Not nice.
Your hair is very nice. It shines like, like red copper. And your skin is
whiter than any skin I have seen. Are you white like that all over
under your clothes?"
"Young man," said Ewing, who had just entered and caught the last
enquiry. "You are vairy indiscreet. Leddies do not possess what they
do not please to show us."
"No?" Willatopy lifted his eyebrows. "But Madame"—he had caught
the title from Ching—"has such beautiful skin. Her stockings shine,
like rich bronze, and are very beautiful, but I think that her legs
would be much nicer without all those stockings and petticoats."
Ewing grinned. Ching frowned. Madame for a moment almost
blushed and then laughed in her old rippling fashion.
"Willatopy," said she, "if you don't mind we will change the subject.
White men don't talk like that about white women, and you must try
to behave like a white man. It was all your fault, Alexander," she
went on severely. "If you had left the boy alone I would have dealt
with him myself. How often must I tell you that Scotsmen have no
tact?"